Configuring the LDAP import method

If your company uses an active directory service to store people information, you can configure your BMC Helix Innovation Suite environment to import that information by using the integrated lightweight directory access protocol (LDAP) functionality. This method is available as a selection on Step 6 People in the Onboarding Wizard. After you configure the Onboarding Wizard to use the LDAP import method, use the same settings to import the information on an ongoing basis to update and add new people to the production data.

Before you can use this method, make sure that your DMT Admin (Data Management tool) configures a connection to the LDAP server. You can configure connections to as many LDAP servers as you need to.

You can perform the following operations by using the LDAP import method:

Onboard non-support people data.
Synchronize the directory with your people data, by running the LDAP import at regular intervals.

Important

To use the LDAP import method, you need DMT User permissions. If you need to configure an LDAP connection, you need DMT Admin permissions.

You can import support and non-support People information directly from your company's active directory by using the LDAP import method discussed in Onboarding Foundation and Assignment data.

Before you begin

Before you can use the LDAP method, you must configure your system to support it.

To perform the procedures described in this topic, you need DMT Admin permissions (for working in the Data Management console) and AR System Administrator permissions (for working in the BMC Atrium Spoon client).
In these procedures, make sure you identify an LDAP attribute that is unique to each record (for example, objectGUID) to help identify records that have errors during the import process.
If you import Support people information, you will need to open the records after you import them to add permissions.

LDAP configuration overview

To configure your system to support the LDAP import method, perform the procedures displayed in the following diagram.

Tip

Click the procedure name to see information about how to perform the procedure.

The LDAP import method configuration

To create a transformation

Use a template to create a new transformation in the the Atrium Integrator Spoon client. This transformation provides mappings between the LDAP user attributes and the fields on the CTM:LoadPeople form.

On the computer where the Atrium Integrator Spoon client is installed, select Start > Programs > BMC Software > AR System > BMC Atrium Integrator Spoon.
In the Atrium Integrator Spoon window, select Tools > Repository > Explore.
Locate and open the transformation template for the connection protocol you will use:
- BMC_Onboarding_Template_LDAP_People
- BMC_Onboarding_Template_LDAP_People_Secure (for LDAP SSL)
- LDAP_People
- Secure_LDAP_People_Secure (for LDAP SSL)
Make a copy of the template by renaming it:
1. Click File > Save as.
2. From the Transformation Properties dialog box, in the Transformation Name field, type the new name.

In the transformation diagram, double-click the DMT_LDAP_INPUT step; then make the following entries in the LDAP Input dialog box:

Change the default values in the General and the Search tabs to match those of your LDAP environment.
Later, in sub-step e, you will restore these default values. The table that you can open in sub-step e provides a list of the default values, so you don't need to make a note of them now.
The fields are case sensitive.
Ensure the Trust Store Path that you specify in this step is accessible by the Atrium Integrator Spoon client.
(Optional) On the General tab, click Test Connection to confirm that you can connect to the LDAP server with the information that you provided in the General tab.
Open the Fields tab and click Get fields to retrieve the LDAP user attributes from the LDAP server.
When the transfer of LDAP user attributes is complete, review the attributes to confirm that they are correct and that they are String type.
For example, make sure that the Type value for each attribute is valid, based on the information that is contained within the attribute.

Restore the default values and selections used for each setting in the General and the Search tabs.
The following tables and illustrations show you the default values. You can cut and paste the text in the table back into the fields.

Default values and selections for General and Search tabs

General tab

Although you cannot see the value of the Password field because of the mask, ensure that you specify the default password: ${Bind_Password}.

You need to restore the default values to the Certificate fields (the red box in the illustration that follows) only if you are using the BMC_Onboarding_Template_LDAP_People_Secure template.

For your convenience, you can copy the default values from the table and paste them into the corresponding field.

Field or check box	Default value or selection
Host	${LDAP_Host}
Port	${LDAP_Port}
Protocol Note: The default value depends on the template that you are using.	`LDAP` (BMC_Onboarding_Template_LDAP_People or LDAP_People) or `LDAP SSL` (BMC_Onboarding_Template_LDAP_People_Secure or Secure_LDAP_People)
Use authentication	Selected
User name	${Bind_UserName}
Password	${Bind_Password}
Use certificate (if using the the secure template)	Selected
Trust store path (if using the the secure template)	${Trust_Store_Path}
Trust store password (if using the the secure template)	${Trust_Store_Password}
Trust all certificates (if using the the secure template)	Unselected

Search tab

Field or check box	Default value or selection
Dynamic search base	Not selected
Search base fieldname	Not available
Search base	${Search_base}
Dynamic filter string	Not selected
Filter string fieldname	Not available
Filter string	${LDAP_FilterStr}

Click OK to close the dialog box.

In the transformation diagram, double-click the Define LDAP Unique Identifier step.
Important

In this step, you identify an LDAP attribute that is unique to each record, for example, objectGUID. The actual unique identifier that you use depends on the specifics of your environment.
The LDAP Unique Identifier that you specify here is used to identify problematic records in the import error log. If an error occurs during the LDAP import, the system provides you with a link to an error log that you can use to identify which record had a problem and what the problem was. After you identify the problematic record, you can choose to edit it in the active directory or to filter it out of the LDAP import using a custom search filter.
1. In the Formula column of the Formula dialog box, click LDAPUniqueAttributeName and in the edit box that appears, type the name of the LDAP unique attribute to use as the identifier. Make sure that you enclose the value in double quotes; for example, type objectGUID.
2. To close the edit box and save the update, click OK.
3. In the Formula column of the Formula dialog box, click LDAPUniqueIdentifier and in the edit box that appears, type the name of the LDAP unique identifier. Make sure that you enclose the value in square brackets; for example, type objectGUID.
  The name that you provide for the LDAPUniqueAttribueName and the LDAPUniqueIdentifier must be the same, as shown in the examples provided in sub-steps a. and c. Only the enclosing characters, that is, the double-quotes and the square brackets are different.
4. To close the edit box and save the update, click OK.
5. Click File > Save.

For BMC Helix ITSM version 9.1.03, in the transformation diagram, double-click AR Upsert step.
If you have an existing connection to the AR System server, you can use that connection in this step. If you have an existing connection, you can skip sub-step a.

Click New to create a new connection for the AR System server.
The Database Connection dialog box opens. If you chose to perform this step, you will be able to use the new connection in future transformations.
Click Test to test the connection with the AR System server.
If the connection is working, click OK twice, to dismiss the system message and then the dialog box.
Open the Field Mapping tab, then click Edit Mapping.
The Enter Mapping dialog box opens.

Create the mappings between the LDAP user attributes and the fields on the CTM:LoadPeople form.

In the Enter Mapping dialog box, make a selection from the Stream fields column (where the LDAP user attributes are listed)
Make a corresponding selection from the Form Fields column (where the CTM:LoadPeople form fields are listed),
Click Add.
Map the following CTM:LoadPeople fields as shown below:

For BMC IT Service Management versions 9.1.02 and earlier:

LDAP attribute	People form field
Parent_Job_GUID	Parent_Job_GUID
Parent_JobID	ParentJobID
Assignee Groups	Assignee Groups
JobCompany	Company
LicenseType	License Type2
LDAPUniqueIdentifier	Alternate ID
UDMSource (Applicable only to Onboarding Wizard)	UDM_Source

For BMC IT Service Management versions 9.1.03 and later, see Configuring Data Management for LDAP or LDAPS import .

Map the following required CTM:LoadPeople form fields to the corresponding Stream fields (the names of the Stream fields can vary, depending on your LDAP environment):
- Last Name
- First Name
- Site
To save the mappings, click OK.

Open the General tab and from the Connection list, select AR Server.
Tip

To verify that you chose the correct connection, click Edit and check the AR System server connection variables in the Database Connection dialog box. If these variables are not present or are incorrect, check that you selected the correct connection. If you selected the correct connection, then you need to re-enter the variables.
For BMC Helix ITSM version 9.1.03 and later, click OK to save, and close the AR Upsert step.
In the Atrium Integrator Spoon window, click the Save icon to save the transformation.
If you are continuing now with the next procedure, leave the Atrium Integrator Spoon client open; you will perform the next procedure in the Spoon client.

To create the Atrium Integrator job in the Atrium Integrator Spoon client

Use a template to create a new job in the Atrium Integrator Spoon client. In the next procedure, point to this job from the Atrium Integrator Jobs console of the BMC Helix ITSM Data Management component.

From the repository, open BMC_Onboarding_Template_LDAP_People job template for the connection protocol you will use:
- BMC_Onboarding_Template_LDAP_People
- BMC_Onboarding_Template_LDAP_People_Secure (for LDAP SSL)
Make a copy of the template by renaming it:
1. Click File > Save as.
  The Job Properties dialog box opens.
2. In the Job Name field, type the new name.
In the job diagram, double-click the BMC_Onboarding_Template_LDAP_People step; then make the following entries in the Job entry details for this transformation dialog box:
1. In the Name of job entry field, type the name that you created in Step 4 of the procedure to create the transformation.
2. On the Transformation specification tab, change the content of the Specify by name and directory to match the name and directory that you entered in Step 4 of the procedure to create the transformation.
3. Click OK to close the dialog box.
In the Atrium Integrator Spoon window, click the Save icon to save the transformation.

To create a connection from the Onboarding wizard to the LDAP server

Set up the connection information from the Onboarding wizard of the Data Management component to the LDAP server and to the Atrium Integrator job.

From the Applications menu on the IT Home page, select Data Management > Onboarding Wizard.
Click Step 6 People.
Open the Create Data Manually list and select Load data into the system using Lightweight Directory Access Protocol (LDAP).
The screen refreshes to display the fields you need for setting up the LDAP connection.
Click Manage Settings.
You can see this icon only when you are logged in with DMT Admin permissions.

In the Manage LDAP Settings dialog box, click Add, and provide the parameters that the Onboarding Wizard uses to connect with your LDAP environment.

Click here to see a list of the parameters with explanations

Parameter	Additional information
Setting Name	A meaningful, unique name for this set of connection parameters. If, over time, you configure multiple LDAP connections in the Onboarding wizard, you use the Setting Name to identify and select this connection from the drop-down menu that is associated with the Setting Name field.
Company	The company for which the connection is being defined.
Host	The host name of the LDAP server to which you are connecting.
Port	The port number of the LDAP server.
Username	The user name that you use to connect to the LDAP server; this username must have permissions to access the people data information you will import.
Password	The password for the username.
Search Base	The name of the directory on the LDAP server (or LDAP "distinguished" name ) from which the Onboarding wizard begins the search for the people records
Atrium Integrator Job Name	Be sure to specify the name of the job that you created in Step 2 of the Creating the Atrium Integrator job in the Data Management console procedure.
(Optional) Use secure connection	Select this if you used the `BMC_Onboarding_Template_LDAP_People_Secure transformation` templates when you created the transformation. If you select this option, you also must supply the following information: Trust Store path—The path to the Trust Store. The Trust Store is where you store the SSL certificates.The AR System server must be able to access this location. Trust Store password—The password for the Trust Store.
(Optional) Use custom filter	If you select this option, you must supply a search filter. The search filter is an argument that the Onboarding Wizard uses to identify on the LDAP server the people records that you need to import. For example, you might indicate: objectClass=Person. In this example, the Onboarding Wizard will import all of the records in the indicated search base on the LDAP server that have an object class of Person.

Click Save.
The system adds an entry for this set of connection parameters to the table in the Manage LDAP Settings dialog box and to the drop-down menu associated with the Setting Name field.
If you later must disable a connection entry from the drop-down menu, highlight the connection in the Manage LDAP Settings dialog box and click Delete to remove it entirely, or click Offline to disable it temporarily.
To update a connection, highlight it in the Manage LDAP Settings dialog box and click View. The connection record opens in edit mode and you can make your changes.
(Optional) Designate a default connection in the Manage Settings dialog box table. Highlight the connection and click Set as Default. If you have a multitenant environment, you can create a default connection for each company.
If you have multiple LDAP environments that reference the same Atrium Integrator job, repeat this procedure and provide different connection information. Be sure to specify the same Atrium Integrator job.

To configure the maximum number of allowed errors

When you run an import using the LDAP method, the import process samples the imported records periodically (be default, every 1000 records) to determine the number of errors encountered in the sampled records. By default, if 20% of sampled records have errors, the import process halts the import. You can configure both of these setting from the AROutput step of the transformation used by the import, as described in the following procedure.

On the computer where the Atrium Integrator Spoon client is installed, select Start > Programs > BMC Software > AR System > BMC Atrium Integrator Spoon.
Open the Repository.
In the Atrium Integrator Spoon window, select Tools > Repository > Explore.
Locate and open the transformation you need to update.
Double-click the AROutput step.
From the Step Error handling settings dialog box, change the following settings according to your needs:
- Max % of errors allowed–The default setting is 20%. If 20% of the records sampled have errors, the error handling feature halts the import process. If you need to disable the error handling feature, clear the field so that it is blank. If the field is blank, the error handling algorithm allows 100% errors, effectively disabling the feature.
- Min nr of rows to read–The default setting is 1,000. This value controls how often the error handling feature samples the import process for errors. For example, if you leave this setting at its default value and the Max % of errors allowed value at its default setting (20%), then after every thousand records are imported, the error handling feature checks the percentage of records with errors. If the percentage is equal to or greater than 20%, the error handling feature halts the import.
Click OK.