Using the Target System (Provisioning) Workflows

When the creation of new objects fails due to missing superior nodes, the realtime workflows automatically try to create them. But there is one limitation: the same structure is required in both in the Identity Store and in the connected system and therefore the individual nodes are mapped one-to-one.

When creating the missing entry in the connected system, the workflows use the following attributes from the appropriate entry in the Identity Store:

Assume that "c=de" exists, but nothing else. Then:

The realtime workflows will create the missing superiors as far as possible.

A) If a superior node doesn’t exist in the connected system, they create the relevant entry in the Identity Store with a default attribute list:

B) If the superior node exists in the connected system, the workflows use the following attributes from the appropriate entry in the connected system:

In the Advanced tab of the target system object, the properties Type, Forest and Domain must be set correctly according to your connected system. The event-based workflows on the Connectivity side assigned to this target system must hold the same values in their Is applicable for section. If a Windows Password Listener is also active in the related Active Directory domain, the property Forest must be specified in the full qualified form, for example “dc=your-company,dc=net” and the property Domain must contain just the name of the domain, like “your-company” to correctly receive the password change requests - keeping this information in their topics- sent by the Password Listener.

dxrPrimaryKey

The dxrPrimaryKey attribute of accounts and groups contains the objects' connected system DN. It is also used as the member attribute of groups. On account creation, it is generated by the tsaccount.xml object description using the target system-specific attributes Account Root in TS and Group Root in TS in the Options tab.

dxrName

The dxrName attribute of accounts and groups contains the target system-unique attribute samAccountName. It is generated with the Java script dxrNameForAccounts if the account or group is created in DirX Identity. It is used for joining in the Identity direction.

In the Options tab of the target system object, the DN values for the Account Root in TS and Group Root in TS properties must be set correctly. They are used to generate the dxrPrimaryKey attribute on creation or modification of an account or group in DirX Identity. The dxrPrimaryKey attribute holds the DN of the object in the connected system.

If an Exchange system is to be provisioned, some basic Exchange attributes must be configured in the Options tab of the target system object. They are used as base values for generating mailbox-specific attributes for an account when the "dxr mailbox users", "dxr shared mailbox creation", "dxr room mailbox creation" or "dxr equipment mailbox creation" groups are assigned to the related user.

To enable an account in DirX Identity for Exchange mailbox functionality, assign the "dxr mailbox users" group to the related user. To make this assignment, you usually create a corresponding role assigned to this group or you assign this group directly. On assignment, the obligations linked to this group set all of the mailbox-enabling attributes that are required to create a mailbox-enabled user in Active Directory. On revocation, these attributes are cleared or set according to revocation.

There are two levels of obligations assigned:

To create a shared, a room or an equipment mailbox in Exchange 2013 or newer, assign the “dxr shared mailbox creation”, “dxr room mailbox creation” or “dxr equipment mailbox creation” group to a user representing this mailbox object in Active Directory. On assignment, the obligation rules for this group calculate and set all attributes required for the relevant mailbox type. On revocation, these attributes are cleared or set to the appropriate value.

To grant permissions to a user in DirX Identity to access a specific shared, room or equipment mailbox in Exchange, create a related rights assigning group in DirX Identity by copying the existing “dxr shared mailbox team1” group and adapt its obligation rules.

The “dxr shared mailbox team1” group is a sample for giving an account the right to share the specific mailbox named SharedMailbox_team1, which must exist already in Exchange. For every shared, room or equipment mailbox in your Exchange system that you want to share, you need to create a shared-mailbox-enabling group - for example, by copying and renaming the sample “dxr shared mailbox team1” group - and adapt the name of the mailbox to be shared in the OnAssignment rule of the Obligations tab, which sets the mailbox name to be shared to the dxmADsExtensionAttribute2. This attribute is then mapped in the ADS synchronization workflow account channel to the target virtual (not in the schema) attribute ps_script_param1 and passed as the first parameter to the specified PowerShell script. The PowerShell script name is set in the OnAssignment rule to the dxmADsExtensionAttribute1 attribute, which is mapped to the target non-schema attribute ps_script_name. The dxmADsExtensionAttribute3 attribute is filled with the cn of the assigned user, which is mapped to the target attribute ps_script_param2 and passed as the second parameter to the PowerShell script AddSharedMailboxPermission.ps1 (running the Add-MailboxPermission cmdlet). The script is executed after the account has been created or updated in the connected system and assigns the rights to access the shared mailbox to the account.

On unassigning these rights, the script RemoveSharedMailboxPermission.ps1 (running the Remove-MailboxPermission cmdlet) is called. This is specified in the OnRevocation rules of the obligations.

The PowerShell scripts AddSharedMailboxPermission.ps1 and RemoveSharedMailboxPermission.ps1 are installed under install_path\samples\ADS\scripts\ and must be copied into the Java-based Server’s repository\scripts folder.

For assigning and unassigning rights for room and equipment mailboxes, you perform the analogous actions and create a rights-assigning group for each Exchange room or equipment mailbox to be shared. The same PowerShell scripts for any mailbox types used for sharing (shared, room or equipment mailbox types) can be used for rights assignment and unassignment.

If an Active Directory system hosting a Skype for Business Server (formerly Lync Server) is to be provisioned, some basic lync-enabling attributes must be configured in the Options tab of the target system object. They are used as base values for generating lync-enabling attributes for an account when the "dxr lync users" group is assigned to that account.

To enable an account in DirX Identity for Skype (formerly Lync) functionality, assign the "dxr lync users" group to this account. To make this assignment, you usually create a corresponding role assigned to this group or you assign this group directly. On assignment, the obligations linked to this group set all of the lync-enabling attributes that are required to create a lync-enabled user in Active Directory. On revocation, these attributes are cleared.

Both Directions

a. Master attributes

You can master attributes by setting the OnAddOnly flag in the according mapping direction. For example, if you want Identity to master a certain attribute, you set this flag in the mapping direction to Identity to let the connected system only set the attribute on an add operation in Identity and vice versa.

If the mapping is more complex, mastering can also be implemented in a Java mapping, as done for the Identifier mapping. The Identifier is mastered by DirX Identity in the default real-time synchronization workflow. In the target system direction, it is set by Identity with the dxrPrimaryKey attribute value and results in moving the object in the target system if dxrPrimaryKey changes. In the Identity direction, the Identifier is calculated only on an add operation, otherwise the joined object’s Identifier is taken.

Special caution is necessary for the attribute proxyAddresses:

The proxyAddresses multi-value attribute is handled as case-sensitive in Active Directory because a value starting with the uppercase letters "SMTP:" is considered to be the primary e-mail address of a user in contrast to possible further values starting with the lowercase letters "smtp:". In DirX Identity, the corresponding attribute dxmEX2kProxyAddresses is not defined to be case-sensitive but is case-insensitive in the schema; this definition should not be changed in DirX Identity for compatibility reasons. Provisioning it can cause the primary address of a user, which possibly might have been changed by an administrator in Active Directory, to be overwritten with the wrong value of lowercase letters on the next synchronization run to Active Directory, regardless of whether or not a validation has been previously performed.

To solve this problem, the OnAddOnly flag can be set in the mapping direction to Active Directory for the proxyAddresses attribute. This setting can be made because the attribute does not belong to the mailbox-enabling attributes, which must be able to be assigned and unassigned at any time during the lifetime of the user.

If you want to set proxyAddresses on both an add and a modify operation, you can uncheck the flag checkModification. In this case, the join engine does not compare the values of the joined entry in Active Directory with the mapped values but just replaces the values as they are in the mapped entry. Then uppercase and lowercase letters are preserved and must just be provided correctly on synchronization to Active Directory.

b. Moving objects

The default ADS real-time synchronization workflow can perform a rename/move in AD as follows:

If the dxrPrimaryKey attribute of the account is changed in Identity (as a result of a user resolution and new calculation of the account attributes, which can have dependsOn or masteredBy settings in the accounts object description), the workflow performs the following tasks:

Direction: Identity → Connected System

a. PostMapping

A PostMapping exists only for the group channel in the target system direction. It is used for changing the request type to DELETE if the dxrState attribute in Identity contains the value DELETED. This results in deleting the object in the target system.

For accounts, the deletion of objects in the connected system is handled in the userAccountControl Java mapping.

The password channel updates the Active Directory account passwords.

The associated SetPassword workflow is started by either the User or the Account Password Event Manager workflow listening for Web Center or Password Listener requests. The Active Directory attributes unicodePwd and pwdLastSet are mapped from the pseudo source attributes dxmPassword and dxmPasswordExpired, which are contained only in the password change request and not read from an LDAP attribute.

The ADS Set Password workflow also resets the lockoutTime attribute to zero (0) to finish the user’s lockout period immediately and to enable him to log in again after his password has been updated.

A password channel can also be configured backwards from the connected system to Identity to be able to update some attributes in Identity after a password change or a reset has taken place in the connected system. The join engine then synchronizes the attributes specified in the corresponding password channel mapping to Identity after the account with its password relevant attributes was updated in the connected system.

For a general explanation of the delta workflows, see the sections under "Java-based Workflow Architecture" in "Understanding the Default Application Workflows" in this guide.

The default delta workflow for Active Directory ADS_Ident_Realtime_Delta is configured with the delta type SearchAttributes in the account and group channels. With this setting and the default search attributes uSNchanged and uSNcreated, the export search filter is extended by searching only for those objects whose uSNchanged or uSNcreated attribute values are greater than or equal to the highest value of the last delta run stored in the Identity domain for each channel.

If you also want to export the objects that were deleted after the last delta run - in addition to the ones that were changed - you must change the delta type to Expert Operational Attributes. This action generates and shows the operational attributes section for the attribute dxm.delta and the placeholder value ${LastDeltaValue}. At runtime, the join engine replaces the placeholder with the last delta state value stored in the Identity domain as a base64-encoded binary value (cookie). It reflects the last value that was returned by Active Directory at the end of the previous delta search.

If operational attributes are used for delta searches, several adaptations must be made at the workflow configuration:

Search Base Adaptations

The ADS connector uses the DirSync LDAP control for doing delta searches. This has the restriction that only root searches are allowed. As a result, the specified search base must be a domain or subdomain; for example, dc=domain1,dc=munich,dc=my-company,dc=net. In the default delta workflow configuration, the search base configured at the ADS Connected Directory channels is beneath an organizational unit.

To restrict the search result to a certain set of objects, any filter can be specified.

Filter Adaptations

In the default workflow, the filter (&(objectClass=user)(objectCategory=person)) is specified. Since deleted objects lose the objectCategory person, eliminate that part of the filter.

Mapping Adaptations

Extend the mapping to Active Directory with the isDeleted attribute by inserting a direct mapping null→isDeleted with the attribute flags readOnly and retrievable set. The mapping function for the dxrTSState attribute in Identity evaluates the flag and sets the value DELETED for the deleted objects.

Mapping Flags Adaptations

Since the DirSync LDAP control returns only changed attributes for an object, you must remove the flag checkModification for every attribute in the mapping to Identity; otherwise, the attributes are deleted in Identity if they have not been changed in Active Directory and hence do not exist in the list of exported attributes.

Hints for Deciding which Delta Type to Use

Technical conditions:

If you want to integrate the delta workflow into an existing target system with real-time workflows configured to synchronize accounts and groups beneath an organizational unit (like the default ADS real-time workflows do), you must use the default settings of the delta workflow (filter extension type) for this target system, because the search base is configured at the channels and used by all workflows of the target system.

Consequently, a delta workflow using operational attributes is

Scenario considerations:

The validation workflow can also recognize changes and deletions made in Active Directory by calculating the differences of the complete set of objects on both sides. It does not evaluate the delta settings resulting in delta exports like the delta workflow does. As a result, there are different possibilities for which workflows and configurations to use depending on your scenario.

If you have a scenario with a validation workflow scheduled to run very infrequently - for example, because it takes a long time due to a high number of users and groups to synchronize - and you want to react to changes - especially deletions - made in Active Directory more often, you should choose the delta type of operational attributes.

If you have the same scenario without the need to react quickly to deleted and moved objects but with the need to react quickly to changed objects, you can use the default delta type of filter extensions.

Moreover, if you have a scenario with a fairly limited set of users, you could schedule a validation workflow more often to recognize the deleted objects and leave the delta workflow with the default settings to recognize the changed objects.

The default Java-based synchronization workflow mapping is configured to provision an Exchange 2016/2019 connected system. The configuration in Provisioning regarding object descriptions and obligation rules for the mailbox-enabling groups is also set up for an Exchange 2016/2019 connected system. This does not affect your existing ADS target systems and workflows.

If you create a new ADS target system with the target system wizard (the type in DirX Identity is still called Windows 2000), the base properties of your specific Exchange system have been set - or can be set afterwards - in the Options tab of the new target system.

The following section describes other issues related to customizations.

Common aspects for all versions greater than or equal to Exchange 2007

The ADS connector and the ADS agent (which is used in the Tcl-based workflows) both generate the mandatory attributes msExchMailboxSecurityDescriptor and msExchMailboxGuid automatically when a user is to be mailbox-enabled. The connecto and the agent determine whether or not a user is to be mailbox-enabled by checking whether the attribute msExchRecipientTypeDetails is contained in the list of attributes to be set, which is true only if a mailbox-enabling group was assigned. All other attributes mandatory for creating a fully-functioning Exchange mailbox are created through the standard obligation rules used as source attributes in the mapping to the AD attributes. For a user update in Active Directory, the ADS connector uses the LDAP interface and the ADS Agent uses the ADSI Interface.

If you want to synchronize additional Exchange attributes, you have the following choices:

Customizing Exchange 2016/2019

If you want to provision an Exchange 2016/2019 connected system and you created a new target system with the target system wizard of the current version, you must apply the following customizations:

Note: Since multi-values can now be directly assigned in obligation rules, the former method of assigning the values in the updateAddressbook.js java script is no longer needed.

Customizing Exchange 2013

If you want to provision an Exchange 2013 connected system and you created a new target system with the target system wizard of the current version, you must apply the following customizations:

Customizing Exchange 2010

If you want to provision an Exchange 2010 connected system and you created a new target system with the target system wizard of the current version, you must apply the following customizations:

Customizing Exchange 2007 or Exchange 2003

If you want to provision an Exchange 2007 or Exchange 2003 connected system and you created a new target system with the target system wizard of the current version, you must apply the following customizations:

DirX Identity provides a general user hook class UserHookRunExecutable, which allows running any executable configured in a realtime workflow channel object. For the preUpdate and the postUpdate methods of the user hook, an executable with a command line can be configured in the specific attributes pre_executable and/or post_executable of the channel. The corresponding command lines are specified in pre_cmdline and/or post_cmdline. In the postUpdate case, the executable is only called if the update (add or modify) of the object was successful.

The UserHookRunExecutable class starts powershell.exe - as a specific executable - only if a PowerShell script name is passed to it as a parameter; otherwise it just logs that nothing needs to be done. This configuration allows always specifying the UserHookRunExecutable class in the General tab of the Accounts channel (and of course any other channel), because the PowerShell script name is now only set with a non-empty value in the standard mapping if a permission-granting mailbox group is assigned to the associated user. In all other cases, the script name is not populated and hence powershell.exe is not started.

This behavior, along with setting the script name depending on whether or not other (rights-representing) attributes are set, is also useful for modeling other customer-specific requirements.

Common Architecture for Running Executables

The common architecture and features for running executables from a user hook are described in "Running Executables from a User Hook" in "Understanding the Default Application Workflow Technology".

PowerShell Prerequisites

A PowerShell script can use the cmdlets that are part of the locally-installed PowerShell instance and it can also use and remotely run cmdlets that are only part of the remotely-installed PowerShell instance. You can even call PowerShell 64-bit cmdlets from clients running a PowerShell 32-bit version.

You need to have the Windows Management Framework installed to use PowerShell cmdlets that reside only on the remote server and not on the client machine’s locally installed PowerShell instance. An example is to administer Exchange using the remote Exchange management cmdlets without having them installed locally.

Windows Management Framework includes Windows PowerShell V2 and Windows Remote Management (WinRM) 2.0, which is the Microsoft implementation of the SOAP-based WS (=Web Services)-Management Protocol.

For Windows 7 or Windows Server 2008 R2 and newer, the correct version of the Windows Management Framework is already installed.

Required PowerShell Settings

Apply the following settings to enable the remote server to execute PowerShell commands. For Windows versions greater than or equal to Windows Server 2012, this is usually already enabled by default and so none of the following settings need to be explicitly applied.

Server-side settings:

Call the command enable-psremoting in the Administrator PowerShell of the remote server. It creates a listener for HTTP connections and sets firewall exceptions for Http port 80 and Https port 443.

Client-side settings:

Call the command set-executionpolicy remotesigned in the Administrator PowerShell of the client to enable it to run scripts.

The standard ADS real-time workflow account channel is pre-configured to run any PowerShell script - after the account is updated in the connected system - that is passed as a parameter in the source attribute dxmADsExtensionAttribute1 mapped to the target attribute ps_script_name. The script parameters are set in additional extension attributes depending on the groups that are assigned to the accounts’ associated user. Script name and parameters are then passed to the post_cmdline specific attribute, which is taken as input for running powershell.exe specified as the executable in post_executable. The extension attributes are cleared in the mapping back to Identity to prevent the PowerShell script from being started again on the next synchronization run.

Running an Exchange cmdlet in the Java-based Server

In addition to the PowerShell scripts AddSharedMailboxPermission.ps1 and RemoveSharedMailboxPermission.ps1, which are used in the standard ADS realtime synchronization workflow for assigning mailbox rights, DirX Identity delivers sample scripts that contain Exchange cmdlets. These scripts are installed under install_path*\samples\ads\scripts*.

The DisableMailbox.ps1 sample script expects two parameters: one for identifying the mailbox (user principal name) and one for identifying whether or not the mailbox shall be disabled. This parameter can also be set independently from the msExchHideFromAddressLists attribute. It is taken here as one reasonable way for specifying enabling or disabling a mailbox, because a disabled mailbox should also not appear in the global address lists.

The DisableMailbox.ps1 script uses the Disable-Mailbox cmdlet. In addition to removing all mailbox-enabling attributes from the Active Directory user, the Disable-Mailbox cmdlet also performs a cleanup task on the mailbox, disconnecting the mailbox immediately from the user so that you don’t need to wait for a nightly maintenance complete mailbox database cleanup task.

The ConnectMailbox.ps1 script uses the Connect-Mailbox cmdlet, which reconnects a disconnected mailbox to an Active Directory user.

If you want to create a new mailbox for an existing Active Directory user, the Enable-Mailbox cmdlet must be used. You can easily create a new PowerShell script for this task simply by copying the ConnectMailbox.ps1 script to a new script - for example, EnableMailbox.ps1 - and then exchanging the Connect-Mailbox cmdlet with Enable-Mailbox, which expects the same parameters as Connect-Mailbox.

Note: If you want to mailbox-enable a user by running an Exchange cmdlet (for example, Enable-Mailbox for an existing user or New-Mailbox for a new user) instead of setting the mailbox-enabling attributes with the standard ADS synchronization workflow, adapt the workflow mapping and the obligation rules of the dxr mailbox users group appropriately depending on the attributes you want to pass to the cmdlet as parameters. Cmdlets usually offer a lot of variation on which parameters can be passed and which are set with default values. Read the Microsoft documentation about the complete functionality of each cmdlet you want to use.

Running a Lync cmdlet in the Java-based Server

You can also extend the standard ADS real-time workflow to run a PowerShell script containing Lync cmdlets to be executed on the remote Skype for Business Server (formerly Lync Server). For an explanation about how to pass parameters to the script, how to provide credentials and where to place the script, see the instructions given in "Running an Exchange cmdlet in the Java-based Server".

The sample script LyncEnableUser.ps1 is installed under install_path*\samples\ads\scripts*. Running it is an alternative way to lync-enable a user instead of doing it by mapping all lync-enabling attributes produced by the obligation rules of the dxr lync enabling group as done in the default ADS real-time workflow.

The LyncEnableUser.ps1 script uses the Enable-CsUser cmdlet for lync-enabling a user. The Disable-CsUser cmdlet is also described in this script as well as other lync-handling cmdlet samples.

In order to be allowed to remotely execute the cmdlets, a secure connection to the Lync Server over https is required. As a prerequisite for such a secure connection, the root CA certificate that issued the lync-related certificates must be imported into the Trusted Root Store of the workstation running the script.

Remote Folder Management can be performed using the related PowerShell cmdlets, but you can also use this older tool described here.

The functionality described here allows the management of folders and shares on a remote computer running the Windows 2003 Server operating system or newer. You can use it in a user hook or in the attribute mapping code of a Java-based workflow. It can create and delete folders on a remote computer and copy/move folders between remote computers.

Architecture

The remote execution works over $ADMIN and $IPC shares on the remote computer. The external CLI utility accesses the $ADMIN share to set up the remote listener service and then passes remote commands via $IPC share. Results and outputs from these commands are returned to the Java code. The following figure illustrates this control flow:

With the exception of ssh, all of the tools use $IPC and $ADMIN shares. The remote management functionality that has been used and tested in customer projects includes:

CLI Tools

To enable remote management, you need to select a toolkit. The following list evaluates tools that can be used to execute commands remotely. xCmd is the preferred tool.

xCmd

+ freeware
+ nothing required on target machine (service is copied automatically)
+ sources are available
- works only between Windows machines

For more information and for download, visit: http://www.codeguru.com/Cpp/I-N/network/remoteinvocation/article.php/c5433

PsExec

+ nothing required on target machine (service is copied automatically)
- works only on Windows machines

For more information and for download, visit: http://technet.microsoft.com/en-us/sysinternals/bb897553.aspx

winexe

+ freeware
+ sources available
+ nothing required on target machine
- works only from UNIX to Windows machines

For more information and for download, visit: http://sourceforge.net/projects/winexe.

ssh

+ freeware
+ sources available
+ reliable
+ works from any of the supported platforms to any other
- needs ssh-keygen to prepare ssh keys so that it doesn’t prompt for a password.
- manual sshd installation on remote machine required

Support Utilities

The following set of utilities provides useful functions on a remote machine.

Part of standard Windows installation:

External utilities:

Requirements

To set up and use folder management based on the xCmd utilities:

Deployment

Usage Sample

This functionality can be used, for example, to implement the creation of user home and profile folders with appropriate shares on a given user home server within Active Directory target system provisioning:

Some permanent configuration information is stored as target system environment variables (root of home folders, default permissions to be set). Account credentials to connect remotely to the home server are extracted from the target system connection obtained from the environment (same account used).

The user hook is bound to the account channel of the target system. The channel mapping manages the homeFolder and profilePath attributes of Active Directory. When creating the folders after a new account is created, permissions are not set within the given user account name, but within the user SID, because the home server does not know about the new account immediately.

The user hook handles the following situations:

Additional Information

For additional information, search for the FolderManager.java class under the Additions\RealtimeWorkflows folder of the DirX Identity delivery media. It contains a channel user hook template for creation of the account home folder and share.

Direction: Identity Store → ESSO

com.siemens.dxm.join.userhook.esso.UserHookAccountsTo

Implements the "Process Source Entry" procedure. It reads the user link of the source entry and tries to find the corresponding account in the ADS/LDAP ESSO target system. It provides the DN (in the connected system) of this account and the State attributes in the following environment properties: essouser, essouserstate, essousercsstate.

If the account cannot be found, it returns false and the entry will not be processed (you can’t manage Evidian ESSO accounts without an Active Directory account).

A simple expression is used:

The user DN part of the identifier is taken from the environment property essouser which is populated by the processSourceEntry user hook. The application part is taken from the essoapplication environment property. The join expression is just a dummy as the connecter does not support filters. The whole Join criteria is given by the base DN, which identifies exactly one account in the ADS/LDAP ESSO connected system.

ID mapping is a Java source mapping. It corresponds to the base object of the export (if no joined entry is found):

Post mapping is a Java source mapping. The following attributes control the outcome:

The application is defined as a Specific Attribute at the channel configuration object.

If you want to use another attribute or another mechanism to define whether an account should be enabled for SSO:

By default, "cn=Accounts,"${env.assocts}"* is used as the search base. If your associated target system holds accounts and groups in the same folder, you need to change this to: *"cn=Accounts and Groups,"${env.assocts}".

Direction: Identity Store → Imprivata OneSign

Direction: Imprivata → Identity Store

Direction: Identity Store → Imprivata OneSign

Direction: Identity Store → Imprivata OneSign

Direction: Identity Store → Imprivata OneSign

A password channel updates the subscriber and account passwords.

A password channel can also be configured backwards from the connected system to the Identity Store to be able to update some attributes in Identity after a password change or reset has taken place in the connected system. The join engine then synchronizes the attributes specified in the corresponding password channel mapping to the Identity Store as usual after the account with its password-relevant attributes is updated in the connected system.

Attributes in the DirX Identity target system belong to the corresponding attributes in the JDBC target system.

Direction: Identity Store → JDBC

Direction: JDBC → Identity Store

Direction: Identity Store → JDBC (TS Account-Group-Membership)

In most cases, your database table(s) will differ from the assumed default tables.

Table Names

In every mapping where the syntax Tablename.ColumnName is used, change the table name

IDMapping → JDBC:

Column Names

You can change the column names directly in every mapping line. If you want to select attribute names from a list, you must edit the JDBC CD attribute configuration.

If column names of the columns holding the unique identity attribute (by default, dxrGroupName, dxrAccountName) differs, adjust this in JDBC CD SpecificAttribute accountnameatt / groupnameatt

Primary Key is not an Auto Key

This is not possible in pure lite mode. Define instead the primary keys (in TS port):

Here a separate ID column in the membership table is assumed. It’s also possible account-id and group-id defines the key. In this case the definition of the membership table and the corresponding abbreviation is not needed.

Use the defined abbreviation for id column in ID mapping

Use CommonProcsJdbc.calculateIdInJdbc with argument autogeneratedkey=false.

Use the defined abbreviation in members channel as the primary value in Primary Channel join condition.

Use the defined abbreviation in join condition

Use the defined abbreviations in Primarykey(old) and DxrName Java mapping at Identity side.

Change the object description to generate a unique key for dxrPrimaryKey.

Use a Column to specify the Account State

To configure a column representing the account state in your account table insert a new line at the JDBC connected directory propertypage Specific Attributes. As name enter accountstateatt. Fill in the column name as value. The default dxrTSState Mapping for the account uses this column to set the dxrTSState if the configured column exists. Only the values ENABLED and DELETED are allowed. If your column contains other values, you must map your values to these allowed values. To do this edit the dxrTSState mapping at the account channel.

Under the default JDBC TS port, you will find an example for a stored procedure definition.

The sample represents a SQL server stored procedure returning 0 on success. It takes two parameters: the ID that identifies the record and the password that should be set.

To call this stored procedure, an extended request is necessary. This request may be called in the postmapping or in a user hook. Building the extended request in the postmapping means that it is called after a normal request.

Call via postmapping:

In the default setPassword channel, you will find an example (in comments):

Here the first argument ID is taken from the source attribute dxrprimarykey.

The second argument is taken from the mapped entry. This example shows that you can do some complicated mapping and take the result as an argument. Keep in mind that for mapped attributes, modifications will be generated. If you do not want the password to be set twice (by generated modification an by stored procedure) you can use the attribute flag Readonly to prevent it. In this sample, the RequestType is set to NONE at the end, which means that only the stored procedure is called and other generated modifications are ignored. Normally you do not intend to do this, so all generated modifications are made (for example, the description has changed) and afterwards the stored procedure is called to set the password column.

In the com.siemens.dxm.join.userhook.jdbc.UserHookAccountsTo user hook, you will find an example of how to call a stored procedure in a user hook.

What’s the difference?

In a user hook, you must call the connector’s extendedRequest method explicitly. In postmapping, you just build the extendedRequest and add it to the mapped entry:

General Notes:

Function or Procedure?

The definition of a stored procedure may depend on the database system. For the JDBC connector definition, a function is defined if it returns a value. If no value is returned, it is a procedure.

Here is a Microsoft SQL Server 2005 stored procedure:

This stored procedure returns an int, which means you must configure this procedure as a function:

In Oracle, a stored procedure does not return a value, which means you must configure a procedure. But for a procedure, you must specify the "return" argument because the connector needs an indicator for the outcome of the procedure. Therefore, you cannot use a procedure with the same arguments in Oracle. You must wrap the procedure to get an "out" argument for return:

Master attributes:

Most attributes (except, for example, the dxrTSState attribute) are mastered by DirX Identity. Consequently, these attributes have the OnAddOnly flag in the mapping direction to Identity. This is particularly true for the Identifier, which is also mastered by DirX Identity in the default real-time synchronization workflow. In the target system direction, it is calculated by DirX Identity in the dxrPrimaryKey attribute and results in moving the object in the target system if dxrPrimaryKey changed. In the DirX Identity direction, the Identifier is calculated only on an add operation, otherwise the joined object’s Identifier is taken.

Moving account objects:

The default LDAP real-time synchronization workflow can perform a rename/move of accounts in the LDAP target system. It operates in the following way:

If the dxrPrimaryKey attribute of the account is changed in DirX Identity (as a result of a user resolution and new calculation of the account attributes, which can have dependsOn or masteredBy settings in the account’s object description), the workflow performs the following actions:

Changing the account state holding the attribute employeeType:

If you want to use another attribute for holding the account state than employeeType you must do the following mapping adaptions in the account channel:

Direction Identity → Connected System

Just change the java mapping line with employeeType on the right side by exchanging employeeType with another attribute name. The content of the Java coding on the left side has not to be changed because it references now the term tgtAttrname instead of hard coded employeeType. The Java class name is just changed to the new attribute name if the mapping is saved.

Direction Connected System → Identity

Adapt the Java mapping to the target attribute dxrTSState and exchange employeeType in the line
CommonProcsLdap.setAccountStateAttr("employeeType");
by the new attribute name.

PostMapping:

A postMapping exists only for the group channel in the target system direction. It is used for changing the request type to DELETE if the dxrState attribute in Identity contains the value DELETED, which results in deleting the object in the target system.

For accounts deletion of objects in the target system is handled in the Java mapping to the account state holding attribute, which is by default employeeType.

The target system’s password attribute userPassword is updated with the current password of the account in DirX Identity and the pwdReset attribute, which determines whether or not the password must be changed on the next login by the user, is set depending on the source attribute dxmPasswordExpired. This attribute was previously set by the User or Account Password Event Manager workflow listening for requests from Identity Web Center or Password Listener.

If you want to enable case-sensitive renames like ou=RedFlag → ou=Redflag, you need to set the operational attribute caseExactRDNComparison to true in the generated request. Use the Op. Mapping tab of your channel get this into the workflow:

This section describes the mapping and user hook details of the direction Identity Store to IBM Notes. Complex post-mappings and user hooks are required because the Notes target system handles some of the update requests asynchronously (using the adminP process) and problems arise if the previous request has not been successfully processed when the next request arrives. Therefore the Notes real-time workflows use an internal attribute dxrPendingRequest that indicates whether or not a request can be sent to the Notes system without resulting in an error. For details, please refer to the following sections.

For a complete list and explanation of Notes-specific attributes, see the attribute section of the Notes connector description in the DirX Identity Connectivity Reference.

Post-Mapping for Groups

If the attribute dxrState in Identity Store is "DELETED", the operation (as part of the mapped entry) is set to DELETE.

Post-Mapping for Accounts

If the attribute dxrState in Identity Store is “DELETED”, the operation (as part of the mapped entry) is set to DELETE and the value of the attribute DeleteMailFile is set to 0.

For Modify Requests, the following steps apply:

AC - com.siemens.dxm.join.userhook.notes.UserHookAccountsTo (user hooks for accounts)

The following user hooks are used:

User hook preUpdate

Assignment of a new profile updates these attributes:*
PathFileTargetCertId* (derived from the attribute PathFileCertId of the new profile)
TargetCertifier
Validity

If the attribute dxrProfileLink is not set (for example, because the account was created in an earlier DirX Identity version that did not support this attribute) then the user hook preUpdate evaluates a profile name using the value of ou.

User hook postUpdate

After a successful update in Notes this user hook checks whether the attribute dxrPendingRequest needs to be set. The existence of the attribute dxrPendingRequest guarantees that no other critical update operation (rename or move) on the same objects is initialized while the previous one is still running.

The check comprises these tests:

The format of the attribute dxrPendingRequest is:

date=date;PendingOperation=operation;PathFileCertId=value;PathFileTargetCertId=value;FullName=value

Furthermore, if a requested move operation was successful, then the attribute dxrProfileLink is set to the value of the previously evaluated newProfileName (see the preUpdate user hook).

This section describes the user hook details of the direction Identity Store to IBM Notes.

For a complete list and explanation of Notes-specific attributes that are kept in the Identity Store, see the attribute section of the Notes connector description in the DirX Identity Connectivity Reference.

AI - com.siemens.dxm.join.userhook.notes.UserHookAccountsFrom (user hooks for accounts)

The following user hooks are used:

User hook postUpdate

A password channel updates the account passwords.

A password channel can also be configured backwards from the connected system to Identity to be able to update some attributes in Identity after a password change or reset has taken place in the connected system. The join engine then as usual synchronizes the attributes specified in the corresponding password channel mapping to Identity after the account with its password-relevant attributes was updated in the connected system.

Direction: Identity Store → MAIL:

Direction: MAIL → Identity Store

Under Policies → Rules → Consistency → Mail you can find the following rules:

There are two policy execution workflows, one for scheduled use (Email Notification handling), the other event-based (EventBased Email Notification Handling). Both will execute the consistency rules defined in the Policies → Rules → Consistency → Mail section.

To support the business logic and keep track of when an email should be sent, and when not, a new auxiliary objectClass "dxrSender" was introduced that contains the attributes dxrNotifySend and dxrNotifySent. While they are free for use, the intention is to write any trigger, that should lead to an email being sent, into dxrNotifySend, this could be for example the context for the email. When an already sent email is being moved to the sent folder, the dxrNotifySent attribute is set to the same value as dxrNotifySend together with a timestamp. This way you can keep track of all emails related to an entry.

Direction: Identity Store → Medico

Direction: Medico → Identity Store

Direction: Identity Store → Medico

Direction: Medico → Identity Store

Direction: Identity Store → Medico

LC - com.siemens.dxm.join.userhook.medico.UserHookAccountsTo

Direction: Medico→ Identity Store

LI - com.siemens.dxm.join.userhook.medico.UserHookAccountsFrom

A password channel updates the login passwords.

A Password Channel can also be configured backwards from the Connected System to Identity to be able to update some attributes in Identity after a password change or reset has taken place in the Connected System. The join engine then as usual synchronizes the attributes specified in the corresponding Password Channel Mapping to Identity after the account with its password relevant attributes was updated in the Connected System.

Direction: Identity Store → Microsoft 365:

AC - com.siemens.dxm.join.map.office365.accounts.to.UserHookSyncServicePlansAndSkuId

Direction: Microsoft 365 → Identity Store

AI - com.siemens.dxm.join.map.office365.accounts.from.UserHookGetServicePlans

Direction: Identity Store → Microsoft 365

Direction: Microsoft 365 → Identity Store

Direction: Identity Store → Microsoft 365

RC - com.siemens.dxm.join.map.office365.roles.to.UserHookRolesTo

Direction: Microsoft 365 → Identity Store

Direction: Identity Store → Microsoft 365

SC - om.siemens.dxm.join.map.office365.plans.to.UserHookServicePlansTo

Direction: Microsoft 365 → Identity Store

A password channel updates the Microsoft 365 account passwords.

The member channel configuration holds the mapping of the group members.

Direction: Identity Store → Microsoft 365

Direction: Microsoft 365 → Identity Store

Direction: Identity Store → WinLA -OpenICF

Direction: WinLA -OpenICF → Identity Store

Direction: Identity Store → WinLA -OpenICF

Direction: WinLA -OpenICF → Identity Store

Direction: Identity Store → WinLA-OpenICF

Direction: Identity Store → WinLA-OpenICF

The members channel must be referenced from the accounts channel. Note the following attributes:

racfid

The racfid is used as an identifier for users in RACF and is stored in the DirX Identity target system account in the attribute racfid.

racfDefaultGroup

The default group for a RACF user is calculated in the channel user hook and passed as an artificial attribute of the source entry. For details on configuring default groups, see the section “Configuring the RACF Target System” in this guide.

racfAttributes

The racfAttributes attribute triggers special processing in the RACF LDAP service and represents their result when reading. The following values related to activating / deactivating a RACF user are set by the connector. They are calculated in the mapping function configured for this attribute:

RESUME – set for unlocking a RACF user.

REVOKE – set for locking a RACF user. After successful processing, RACF sets the value REVOKED.

racfPassword

Make sure to set an initial password when the account is created in the DirX Identity target system and map it from dxmPassword to racfPassword.

When you observe the values PASSWORD or PROTECTED in the user’s racfAttributes in the RACF system, the typical reason is that the user has no password or an expired one. For more details on racfAttributes, see the IBM documentation, for example, https://www.ibm.com/docs/en/zos/2.5.0?topic=information-associating-ldap-attributes-racf-fields.

Note that the attributes racfSuperiorGroup, racfOwner, and racfSubGroupName are only read from the RACF system.

The racfid is used as identifier for groups in RACF and is stored in the DirX Identity target system group in the attribute racfid. Note that the racfid cannot have more than 8 characters.

The members channel must be referenced from the accounts channel.

Password change operation

The old password must be part of the password change request because RACF does not allow resetting a password. After the password is set, the connector performs an extra bind operation with the RACF user and the old password to set the new password. The two passwords are delivered in one string, separated by a slash character, for example, oldpassword/newpassword.

The Salesforce connector acts as a remote application to the Salesforce system. As a result, you need to create a Remote Access application in the Salesforce system before you can use the Salesforce workflows. (For details, see https://developer.salesforce.com/page/Getting_Started_with_the_Force.com_REST_API). To register the remote access application:

Connected App Name; for example, DirXIdentityConnector

API Name; for example, DirXIdentityConnector

Contact Email - your e-mail address

Callback URL; for example, https://localhost:88123/REST-API/callback

Selected OAUth Scopes - select full access (full)

Consumer Key

Consumer Secret

Now your remote access application has been created. Consumer Key and Consumer Secret must be provided in the connected directory for Salesforce as described in "Configuring the Salesforce Workflows".

Salesforce users can’t be deleted. In the Salesforce system, each user has an IsActive attribute that is set to false if the user is deleted. Furthermore the workflow sets the customer specific attribute StatusInfo__c of the Salesforce user to DELETED. So there is another task before you can run the workflows. You have to create the customer specific attribute StatusInfo_c:

The internal name StatusInfo__c is used in the account-channel mapping and in the account-channel Export section as a filter. If you want to use another Salesforce attribute, you must change the account-channel mapping and the account-channel Export section.

The following limitations apply:

Master attributes

Almost all attributes except a few special ones like dxrTSState are mastered by DirX Identity. Consequently, in the mapping direction to DirX Identity, these attributes have set the OnAddOnly flag and in the target system direction this flag is not set.

However, some attributes cannot be changed for single users through the mapping. Those attributes, for example ADDRESS.STREET, are linked to an extra table for a certain group of users, where they are set by the SAP R/3 administrator.

CUA- or non CUA system

The workflow does not need to be adapted depending on whether or not the connected system is a CUA (Central User Administration) system. The workflow mappings and post-mappings handle the difference transparently.

Direction: Identity → Connected System

The attribute dxrTSState is a pseudo attribute of the SAP R/3 connector. That is it is not passed to the SAP R/3 system as an attribute, but is interpreted by the connector, which performs the corresponding actions depending on the values ENABLED, DISABLED or DELETED.

Direction: Connected System → Identity

The attributes ISLOCKED.LOCAL_LOCK and ISLOCKED.GLOB_LOCK, which are set depending on whether a CUA or non-CUA system is connected, are read from the SAP R/3 connected system and converted by the dxrTSState Java mapping to the corresponding states in DirX Identity.

Direction: Identity → Connected System

The group mapping only results in modifications to the corresponding role in SAP R/3 because roles and profiles are not allowed to be created in SAP R/3 via an interface. Add operations are rejected by the SAP R/3 connector.

Direction: Connected System → Identity

The mapping, the export filters and the join filters of the group channels are configured to synchronize SAP R/3 roles - not profiles - to Identity groups.

In both systems, DirX Identity and SAP R/3, accounts hold the memberships. Therefore, no cross-channel relationship is required.

Direction: Identity → Connected System

Post-Mapping

If a non-CUA system is connected, the target attribute ACTIVITYGROUPS.AGR_NAME must be mapped. If a CUA system is connected, the attribute dxrRole.NAME must be set. This action is handled in the Java PostMapping, which must have access to both attributes.

The target systems password attribute PASSWORD.BAPIPWD is updated with the current password of the account in DirX Identity contained in the attribute dxmPassword. The dxrPwdReset attribute of the SAP R/3 connector, which determines whether the user must change the password on the next login, is set depending on the source attribute dxmPasswordExpired. This attribute was set beforehand by the Password Event Manager workflow listening for requests of Web Center or Password Listener.

A Password Channel can also be configured backwards from the Connected System to Identity to be able to update some attributes in Identity after a password change or reset has taken place in the Connected System. The join engine then as usual synchronizes the attributes specified in the corresponding Password Channel Mapping to Identity after the account with its password relevant attributes was updated in the Connected System.

Direction: Identity Store → Service Management

Direction: Service Management → Identity Store

Direction: Identity Store → Service Management

Direction: Identity Store → Service Management

To set up a SharePoint cluster in the Identity Manager:

The result is a structure like this:

The following configuration steps must be performed at each SharePoint target system:

If you don’t want to use the Target System wizard to create the SharePoint workflows, you can also:

To create an SSL connection to SharePoint:

Creating the Trust Store

The trust store is a Java keystore that is created using the keytool supplied with the Java Runtime Environment. The certificate is obtained by exporting it from the Internet Explorer’s key store of trusted root certification authorities.

To create a Java keystore containing this file, call the Java keytool with the following arguments:

keytool -import -alias alias -storepass password -keystore keystore_filename -file certificate_filename

alias can be randomly chosen, and it must be unique if multiple certificates are stored in the keystore.

password is the keystore password. It must be entered later on as the trustStorePassword in the DirX Identity target system configuration.

keystore_filename is the keystore file name. It should have the extension .jks

certificate_filename denotes the file containing the certificate, with the extension .cer

keytool asks if this certificate is trusted. You must answer "Yes" if you want to use this certificate.

Here is a sample call:

This call creates a keystore file SharePointCaCerts.jks containing the certificate exported in the first step. It is called a trust store since it contains certificates of trusted authorities.

Configuring SSL in DirX Identity

Select the DirX Identity target system and choose the Server Connection tab. Set the following parameters to set up SSL:

Site URL - set the site URL beginning with https and using the secure port (by default, 443). A sample structure of the URL is

Path to Trust Store File - set the fully-qualified path name of the trust store file created in the preceding step.

Trust Store Password - set the trust store password. Note that the password should be scrambled or RSA-encrypted.

You must then restart the Java-based Server to apply the changes.

At the SharePoint connected directory, the directory type LDAP is used since the required configuration parameters are almost the same. The clustered workflows ignore the SharePoint target system service and the bind profiles. These parameters are read from the target systems/bind profiles in the Provisioning domain.

The Identity → Group Base property must not be set at the connected directory because it is different for each target system. In a clustered workflow, this value is overwritten by the target system-specific configuration attribute Group Folder → Base DN in the Environment Properties tab (attribute role_ts_group_base) in the Provisioning domain. The Target System → Group Base property of the connected directory must be set even though it is ignored when exporting the groups from the SharePoint server since all groups per site are flat.

Some specific attributes of the Connected Directory are important for the workflows:

accountnameattribute (mandatory) - the name of the LDAP attribute holding the Windows account name in the peer target system’s account objects.

delete_group_enabled - a boolean flag. If set to true, deleting a group in DirX Identity results in a physical deletion of the group in the connected SharePoint site. If set to false, groups are not deleted in SharePoint.

debug_to_screen - a boolean flag. If set to true, extra debug information is written to stdout. This attribute must be set to false in a production environment.

domainnameattribute - the name of the LDAP attribute holding the Windows domain name in the peer target system’s account objects. If no value is specified, the domain of the bind account is added to the account name. In SharePoint Server versions prior to SharePoint Server 2013, the user name is composed of domain\account. In SharePoint Server 2013 and higher, the user name is composed of a claims-based identity type prefix (for a Windows claims identity type, the prefix is i:0#.w|) followed by domain\account. This means that the domain attribute (the default attribute name holding the domain name is dxmAdsDomain) of an account in the peer target system must consist of this claims-based prefix plus the domain name; for example, i:0#.w|domain1.

In SharePoint sites that use the member syntax prefixaccount (for example, ptdssomember:account) the domainnameattribute must be left blank. This leads to the following behavior:

In the sync direction (Identity to SharePoint) the members are created without the domain prefix in the join engine. The SharePoint connector then adds the prefix to the account name.

In the validation direction (SharePoint to Identity), the connector strips off the configured prefix from the members. In the join engine, the corresponding accounts then are searched without domain name, only with the filter cn=account.

If you use both sites with and without user name prefix, it may be necessary that you must configure two SharePoint clusters: one for the use with user name prefix (and empty domainnameattribute), and one for the use for members with syntax domain\account (with domainnameattribute configured).

filterblocksize - the maximum number of account names in one search filter. The account name-to-user mapping is performed via LDAP searches in DirX Identity. This attribute adjusts the maximum number of account names that are combined in one search filter.

Direction: Identity Store → SharePoint

GC - com.siemens.dxm.join.userhook.sharepoint.UserHookGroupsTo

This user hook performs the following mapping functions:

Export Section

Mapping Section

The DirX Identity to SharePoint mapping is:

Identifier - the identifier is created in a Java mapping function. It contains the group’s cn.

objectClass - set to the fixed value "Group"

groupName - the cn of the group.

ownerIdentifier - a Java source mapping that performs the following mapping:

ownerType - a Java source mapping that performs the following mapping:

role - in the sample workflow, dxrHistoryRemoved holds the SharePoint role names. It is directly mapped to the sharePoint role attribute. You must choose your own attribute here if you intend to provision role names.

description - direct mapping to the same attribute.

defaultUserLoginName - a Java source mapping that performs the following mapping:

Operational Mapping Section

Join Section

Direction: SharePoint → Identity Store

GI - com.siemens.dxm.join.userhook.sharepoint.UserHookGroupsFrom

This user hook performs the following mapping functions:

Export Section

Mapping Section

The SharePoint to DirX Identity mapping is:

Identifier - the identifier is created in a Java mapping function. If a joinedId already exists, this value is used. In a validation workflow, the group’s DN is built from the SharePoint groupName and the role_ts_group_base configured at the corresponding DirX Identity target system.

objectClass - defines the object classes required for a target system group.

description - direct mapping from the description in SharePoint.

ownerType - the type of the SharePoint owner is mapped to dxrDefaultGroupType in the sample. You may need to change this mapping if you use dxrDefaultGroupType for other purposes.

owner - the owner is mapped from the ownerIdentifier. Note that the user hook runs prior to the mapping and thus the ownerIdentifier is already a DN here.

cn - the group’s common name is filled with the SharePoint groupName.

dxrHistoryRemoved - this attribute is used to hold the SharePoint role names in the sample workflow. You should change this to another attribute if you intend to provision the roles.

dxrState, dxrTSState, dxrTSLocal and dxrToDo - the standard mapping as, for example, in the LDAP-to-LDAP workflows is used here, too.

Join Section

The member channel configuration holds the mapping of the group members.

Direction: Identity Store → SharePoint

Direction: SharePoint → Identity Store

Mapping Section

The DirX Identity to SharePoint mapping is:

dxrGroupMember attributes - the mapping of the member state attributes is standard for most attributes. Only dxrGroupMemberRemote and uniqueMember are mapped with special Java functions.

dxrGroupMemberRemote - before the mapping, remotemember contains all SharePoint user names that cannot be mapped to a DirX Identity user. This situation occurs if the Windows account is not managed in a peer target system. The Java mapping function maps remotemember to dxrGroupMemberRemote. If no remotemember exists, dxrGroupMemberRemote is deleted.

uniqueMember - in a target system without accounts but with states, uniqueMember must contain all users referencing the group. Once the user is removed from all group members, it is also removed from uniqueMember.

Direction: Identity Store → Unify Office:

Direction: Unify Office → Identity Store

This section provides information on how to set up the Java-based OpenICF connector server.

OpenICF Server

Download a stable installation package for the Java OpenICF connector server on http://www.forgerock.org/openicf-archive.html. We recommend the version OpenICF Java 1.1.1.0 for compatibility reasons. Follow the installation instructions on http://openicf.forgerock.org/connector-framework-internal/connector_server.html. Configure the OpenICF server port, shared secret and create host certificates if you intend to use SSL.

OpenICF UNIX Connector Bundle

Deploy the delivered improved version of the UNIX connector bundle to your OpenICF connector server installation directory. After you have installed the feature for OpenICF connectivity, you can find the UNIX connector in the folder install_path/connectors/OpenICF/bundles/java (the file name is in the form solaris-connector-.jar*). Copy the file to the openicf_install_path*/bundles* directory. If there is an older version of the file solaris-connector-.jar* in this folder, delete it. The configuration of the connector bundle does not require any special steps.

To configure the connection to a UNIX system using an OpenICF connector server:

Direction: Identity Store → UNIX-OpenICF

Direction: Identity Store → UNIX-OpenICF

Direction: UNIX-OpenICF → Identity Store

Direction: Identity Store → UNIX-OpenICF

Direction: UNIX-OpenICF → Identity Store

The hierarchical workflows for the ADS, Exchange, SAP EP UM and LDAP target systems map the hierarchical tree structure of the target system to the DirX Identity target system accounts and groups subtree. They use the DirX Identity attribute dxrPrimaryKey for account and group objects to hold the target system DN of the object.

At the end of the initial load and validation workflows, the AccountRootInTs and GroupRootInTs parameters of the target system object in DirX Identity Provisioning are set to the values specified in DirX Identity Connectivity in the target system connected directory in the provisioning step. They define the account and group root distinguished name (DN) in the target system and are used in DirX Identity to create the dxrPrimaryKey attribute of an account or group object that is created in DirX Identity.

The workflows for the target systems ADS, Exchange, LDAP and SAP EP UM use the dxrPrimaryKey attribute as the reference attribute from a group to an account. Because it holds the DN of the object in the target system, the DirX Identity group member attributes can be mapped directly to the target system member attribute and vice-versa.

The Exchange and SAP EP UM workflows use the dxrPrimaryKey attribute for joining (identifying) a target system object with an object in the Identity Store.

The LDAP workflows use the employeeNumber attribute and the ADS workflows use the sAMAccountName attribute for joining. This usage has the advantage that objects that have been moved in the LDAP or ADS directory are identified in the Identity Store and can be moved there if the flag Rename Allowed is set in the import properties of metacp.

The NT and ODBC non-hierarchical workflows use the cn attribute as the reference attribute from groups to accounts. The ODBC workflows supply an ODBC unique identifier in the dxrPrimaryKey attribute and use it for joining in subsequent workflows. The Windows NT workflows do not use the dxrPrimaryKey attribute; instead, they use cn, which holds the Windows NT account name, for joining.

In the non-hierarchical workflows RACF and SAP R3 UM, the accounts contain the group member lists so that the groups are referenced from the accounts. This flag is set in the target system advanced page. The reference attribute of the RACF target system is the racfid of a group, and the reference attribute of the SAP R3 UM target system is the cn of a group. Neither of these target system workflows use the dxrPrimaryKey attribute. The RACF workflow uses the racfid for joining and the SAP R3 UM workflow uses sapUsername.

The basic assumptions and prerequisites for this activity are:

This activity performs a full or delta export of meta directory entries into a CSV file, which it then imports into an HiPath database. It has the following phases:

In full mode, export works as follows: it selects entries from the Identity Store (filter dxmOprStatus = ENABLED or TBDEL) and transfers them to the HiPath directory. For each entry in the directory search result, it considers the following cases:

In delta mode, there is a slight difference: for directory entries without related HiPath entries:

The HDMSAgent uses a remote copy command in order to transfer files to the remote host, and a remote shell command to execute the HDMS request on the remote host:

The meta controller script controls the remote HiPath system as follows:

To make this work correctly, you must set up the environment. See the section "Setting Up the HiPath Environment" for details.

The basic assumptions and prerequisites for this activity are:

This step performs a full or delta export of HiPath Person (PERS) entries into a CSV file, which it then imports into a meta directory database. The performed steps are:

Notes:

The parameter Multi Master Attribute List (from HiPath2Ident Entry Handling) specifies the list of attributes being subject to the special handling in import as described in this section above. The default setting defines the special handling (including maintenance of attribute dxmOprOriginator) to be applied for attributes telephoneNumber and facsimileTelephoneNumber only.

The parameter Keep Unmastered Attributes (from HiPath2Ident Entry Handling, default “TRUE”) controls whether or not unmastered (for example, manually entered attribute values) will be preserved.

Connectivity to a HiPath system requires a UNIX account that has read and write access over the HiPath XIE interface. UNIX accounts created with HiPath 4000 Manager V3.1 do not have these access rights. To create an account with the required access rights:

Suppose that HDMSAgent runs on system host1 from the account metauser and host1 has the network address ip1. Suppose you want to configure HDMSAgent for interaction with HDMS V3.1 on host2, network address ip2.

First, perform the following steps on host2:

For the actions required on host1, always use the correct (case-sensitive) account name in the login dialog (in our example, metauser instead of Metauser).

We recommend that you test your setup by running rcp, rsh, and remote_hdms by hand, as shown in the following example:

Define a user account, say some_user_account, that is to run HiPath Workflow. We recommend the DirX Identity installation account for this purpose wherever possible. Deviation from this recommendation will imply some extra work when configuring the workflow. Ensure that some_user_account has the permissions to call the HDMS XIE import/export program and has the permissions to manage the related tables using the XIE program, namely

You can also test your setup by running the HiPath Workflow in trial mode.

For example, suppose that HDMSAgent runs on system host1 from the account metauser and host1 has the network address ip1. Suppose you want to configure HDMSAgent for interaction with HDMS V3.1 on host2, network address ip2.

First, perform the following steps on host1:

Now, perform the following steps on host2:

For the actions required on host1, always use the correct (case-sensitive) account name in the login dialog (in our example, metauser instead of Metauser).

We recommend that you test your setup by running scp, ssh, and the remote_hdms by hand. It is essential that the commands scp and ssh execute without requesting a password. The commands can be tested as shown in the following example:

Define a user account, say some_user_account, that is to run the HiPath workflow. We recommend the DirX Identity installation account for this purpose wherever possible; deviating from this recommendation will require some extra work when configuring the workflow. Ensure that some_user_account has the permissions to call the HDMS XIE import/export program and has the permissions to manage the related tables using the XIE program, namely

You can also test your setup by running the HiPath workflow in trial mode.

Example:

In this example, 9 meta directory entries have been detected to be synchronized into HiPath, 3 of them are already up-to-date.

If HiPath workflow has loaded the PERS table and one or more of its dependent tables (COMPIMP, ORGIMP, LOCIMP, and BUILDIMP) were examined for referential integrity, this section shows the number of entries in each table.

For example:

If HiPath workflow does not need to load one or more of these tables (for example, if it detects only up-to-date entries) the section contains a message that the table has not been loaded. For example:

The derived HiPath Updates section shows the HiPath database update actions that the HiPath workflow export comparison phase has determined. A counter exists for each action to be performed in the HiPath database. For example:

In this example, HiPath workflow requests INSERT of 3 PERS-table entries, UPDATE of 1 PERS-table entry, and DELETE of 2 PERS-TABLE entries. In addition, two organizations (ORGIMP table entries) will be created for support of referential integrity.

This section shows a counter for each HiPath update action that HiPath workflow can perform and whether or not it succeeded or failed for this synchronization task. The INSERTs are not counted per-table.

For example:

You must make sure that the HiPath workflow uses the authentication that has been used when testing the remote copy and remote shell command in previous setup steps. Check the Authentication tab of both Jobs of the HiPath Workflow. There are 2 possibilities:

The correct attribute set is chosen implicitly by the HiPath Workflow itself in dependency of the HDMS Version defined in the related HiPath connected directory. This approach is much more comfortable than selecting dozens of attributes one-by-one and putting them into the appropriate order. There is a drawback of this approach:

See section HiPath Tables for valid attribute abbreviations and names for your HDMS/HiPath version.

Note: If the HiPath workflow shall support a customer extended HiPath dataschema, you need to customize the file_attr_list variables:

The default attribute mapping is suitable for a synchronization where entries are joined by a unique identifier (e.g. dxmGUID) which is stored in an unused HiPath attribute (e.g. text3). Moreover, this mapping computes all attributes which are required for creation of person entries and - for HDMS 3.X - implicit creation of additional entries (in tables COMPIMP, ORGIMP, BUILDIMP, LOCIMP).

Please note that target attribute text3 is not appropriate for HDMS US 5.2. For this HDMS release, another attribute must be used (e.g. info3). Please note that target attribute longname is not suitable for HDMS-US 5.2. For this HDMS release, another attribute must be used (e.g. room)

In general, appropriate mappings must be defined for your attributes constituting your join criteria (HDMS Join expression and Joinback expression). The postmapping section updates the ChangeType based on the status attribute which is dxrState by default. If your status attribute is other than dxrState, then you must customize this section and to cross-check your customization with the source selected attributes and the export filter.

Please note some special mapping rules:

Special meaning of empty value - An empty string value (“”) for a HiPath attribute denotes, that the related attribute will be left unchanged when modifying a HiPath entry.

Special meaning of blank value - If you intend to delete an attribute in HiPath in order to synchronize deletion of related attribute in the Directory, then your mapping must result into a blank value.
Example: Suppose you intend to synchronize the ldap attribute description onto HiPath attribute text1. Then you need:

The HDMS Join Expression / Joinback expression parameters define the best-guess-match policy that HiPath Workflow is to use to join meta directory and HiPath entries. Each Attribute in Joinback Expression must correspond one-to-one with an attribute in HiPath Join Expression. For example:

Joinback Expression: surname and givenname

HDMS Join Expression: name and christianname

In this example, HiPath workflow is to match meta directory entries with HiPath entries using a combination of surname and given name. The meta directory sn (surname) attribute maps to the HiPath attribute “name” and the meta directory gn (given name) attribute maps to the HiPath attribute “christianname”. There must be related mapping rules.

These settings assume that each meta directory entry can be identified by a unique identifier which is stored in the attribute “text3” of an HiPath entry. Please note that attribute text3 is not appropriate for HDMS US 5.2. For this HiPath release, another attribute must be used (e.g., info3).

The postmapping computes a filter value to be used on the attribute dxmOprOriginator in the form:

<master name>#dmsidval#*

The dmsidval variable was computed in the mapping table.

This filter works on the dxmOprAttribute that contains values of the form:

mastername#dmsidval#attributename#attributevalue

The specific handling of this attribute is done in the workflow-specific user hook uh::LoopPostJoin.

See the Hicom DMS 3.1 SA4, Service Manual, Section "Import/Export interface API" for full details about XIE interface request/response format and the meaning of the attributes.

1 - CMD - identifier
2 - C - country
3 - O - company
4 - ORG1 - org1
5 - ORG2 - org2
6 - ORG3 - org3
7 - NAME - name
8 - SRTNAME - sortname
9 - CHN - christianname
10 - TIT - title
11 - SAL - salutation
12 - LOC - location
13 - BUILD - building
14 - LNAME - longname
15 - EXT - extension
16 - SWITCH - switch
17 - POS - position
18 - TIENUM - tienum
19 - EXTAREA - ext_areacode
20 - EXTNET - ext_netcode
21 - EXTEXT - ext_ext
22 - FTN - faxnumber
23 - OWNGROUP - owner_group
24 - DIRTRACC - direct_trunc_acc
25 - TEXT1 - text1
26 - TEXT2 - text2
27 - TEXT3 - text3

See the Hicom DMS 3.6, Service Manual, Section "Import/Export interface API" for full details about XIE interface request/response format and the meaning of the attributes.

1 - CMD - Command
2 - C - country
3 - O - company
4 - ORG1 - org1
5 - ORG2 - org2
6 - ORG3 - org3
7 - NAME - name
8 - SRTNAME - sortname
9 - CHN - christianname
10 - TIT - title
11 - SAL - salutation
12 - LOC - location
13 - BUILD - building
14 - LNAME - longname
15 - EXT - extension
16 - SWITCH - switch
17 - POS - position
18 - TIENUM - tienum
19 - EXTAREA - ext_areacode
20 - EXTNET - ext_netcode
21 - EXTEXT - ext_ext
22 - FTN - faxnumber
23 - OWNGROUP - owner_group
24 - DIRTRACC - direct_trunc_acc
25 - TEXT1 - text1
26 - TEXT2 - text2
27 - TEXT3 - text3
28 - TEXT4 - text4
29 - IMPDATA - import_dat
30 - ACCCTRL - access_control
31 - MODDATE - modify_date
32 - EQ - equipment
33-52 - L1-L20 - l1-l20
53 - LPREFIX - l_prefix
54 - EXTCC - ext_cc
55 - COSTCENTRE - costcentre
56 - CHARGEID - charge_id
57 - BANKCODE - bankcode
58 - ACCNUM - accnum

See the Hicom DMS-US 5.2, Service Manual, Section "Import/Export interface API" for full details about XIE interface request/response format and the meaning of the attributes.

1 - CMD - Command
2 - SWITCH - switch
3 - DOMAIN - domain
4 - C - country
5 - O - company
6 - ORG1 - org1
7 - ORG2 - org2
8 - ORG3 - org3
9 - NAME - name
10 - SRTNAME - sortname
11 - CHN - christianname
12 - TIT - title
13 - ADDR - address
14 - LOC - location
15 - BUILD - building
16 - ROOM - room
17 - STATION - station
18 - POS - position
19 - TIENUM - tienum
20 - EXTAREA - ext_areacode
21 - EXTNET - ext_netcode
22 - EXTEXT - ext_ext
23 - FTN - faxnumber
24 - IMPDATA - import_dat
25 - OWNGROUP - owner_group
26 - MODDATE - modify_date
27 - ACCCTRL - access_control
28 - INFO1 - info1
29 - INFO2 - info2
30 - INFO3 - info3
31 - INFO4 - info4
32 - DIRTRACC - direct_trunc_acc
33 - EQ - equipment
34-53 - L1-L20 - l1-l20
54 - LPREFIX - l_prefix
55 - IDF - idf
56 - IDFCABLEPAIR - Idf_cable_pair
57-71 - INFO5-INFO19 - info5-info19

See the HiPath Manager V1.0, Service Manual, Section "Import/Export interface API" for full details about XIE interface request/response format and the meaning, syntax, format and maximum length of the attributes.

1 - CMD - cmd
2 - C - country
3 - O - company
4 - ORG1 - org1
5 - ORG2 - org2
6 - ORG3 - org3
7 - ORG4 - org4
8 - ORG5 - org5
9 - ORG6 - org6
10 - NAME - name
11 - SRTNAME - srtname
12 - CHN - christianname
13 - TIT - title
14 - SAL - salutation
15 - LOC - location
16 - BUILD - building
17 - LNAME - longname
18 - EXT - extension
19 - SWITCH - switch
20 - SEQNUM - seq_num
21 - TIENUM - tienum
22 - EXTAREA - ext_areacode
23 - EXTNET - ext_netcode
24 - EXTEXT - ext_ext
25 - FTN - faxnumber
26 - IMPDATA - import_dat
27 - OWNGROUP - owner_group
28 - MODDATE - modify_date
29 - ACCCTRL - access_control
30 - TEXT1 - text1
31 - TEXT2 - text2
32 - TEXT3 - text3
33 - DIRTRACC - direct_trunc_acc
34 - EQ - equipment
35-54 - L1-L20 - l1-l20
55 - LPREFIX - l_prefix
56 - TEXT4 - text4
57 - EXTCC - ext_cc
58 - CHARGEID - chargeid
59 - BASCHCLASS - basic_charge_class
60 - BANKCODE - bankcode
61 - ACCNUM - accnum
62 - XPREXISTS - xpr_exists
63 - XPRKEY - xpr_key
64 - XPRPIN - xpr_pin
65 - XPRSERVER - xpr_server
66 - XPRVMSADMIN - xpr_vmsadmin
67 - XPRBROADCAST - xpr_broadcast
68 - XPRDCTSEND - xpr_dctsend
69 - XPRDCTRCV - xpr_dctrcv
70 - XPRPWD - xpr_password
71 - XPRNAME - xpr_name
72 - XPRFLAG1 - xpr_flag1
73 - XPRFLAG2 - xpr_flag2
74 - XPRCONNECT - xpr_connect
75 - XPRQUOTA - xpr_quota
76 - XPRRESERVE1 - xpr_reserve1
77 - XPRRESERVE2 - xpr_reserve2
78 - PERSNUM - persnum
79 - DOMAIN - domain
80 - IDF - idf
81 - IDFCABLEPAIR - idf_cable_pair
82-96 - INFO5-INFO19 - info5-info19
97 – VSW – v_switch
98 – HUSID – usid
99 – UMUI – umuid
100 – UMUS – um_user
101 – UMM - um_marked
102 – UMOP - um_operation_id