Active Directory Synchronization

About Active Directory Synchronization

When a scheduled or manual synchronization is run, Active Directory (AD) Synchronization will gather updated information from Microsoft Azure Active Directory, import it into Essentials, and update the corresponding User records. When the synchronization process is run, Essentials User properties and status will be updated to reflect the last saved information in Microsoft Azure Active Directory.

The synchronization process will import to Essentials only the changes (i.e., new users and updated information) that have been made in Microsoft Azure Active Directory since the last synchronization ran, based on the Last Execution date in the job schedule item.

About Active Directory (AD) Field Mapping Records

Active Directory (AD) Mapping records define how fields in Microsoft Azure Active Directory user accounts correspond to fields in Essentials user records. The mappings that are defined in AD Mapping records are used to synchronize data between Microsoft Azure Active Directory and Essentials. The AD Mapping records determine what information should be retrieved from Microsoft Azure Active Directory and where it should be stored in Essentials.

Each AD Field Mapping record contains the following types of fields:
  • AD Field: Defines the source fields in Microsoft Azure Active Directory.
  • Essentials Field: Defines the target fields for the corresponding Active Directory fields in Essentials.

In addition to the pre-configured mappings, dynamic field mapping is supported for AD synchronization; that is, you can map custom fields supported by Azure active directory with Human Resource fields in Essentials using the Field Mappings section in the AD Synchronization page. For instructions, refer to Create Azure AD Connection.

When AD synchronization occurs, data is pulled from the source fields (values defined in the AD Field boxes) and used to populate the value in the corresponding target fields (defined by the Essentials Field boxes).

An AD Mapping record must exist for each Microsoft Azure Active Directory field that you want to map to a Essentials field. Essentials provides a set of baseline AD Mapping record that map standard Microsoft Azure Active Directory fields to fields in Essentials. If you want to change the mappings that are defined through the baseline records, you can modify the records as needed. However, it is recommended that you retain the standard field mappings defined in the baseline AD Mapping records.

About the Active Directory Synchronization Process

When an Active Directory (AD) synchronization operation is performed:
  • The Essentials system will retrieve the information for the Microsoft Azure Active Directory users associated with the Microsoft Azure Active Directory domains that have been defined in Essentials. The corresponding Essentials User records will be updated. Fields in Essentials will be updated with the information in Microsoft Azure Active Directory using AD Field Mapping records.
  • If the Essentials system finds a user in Microsoft Azure Active Directory who does not have a corresponding Essentials User record in Essentials:
    • A User record will be created in the Essentials.
    • The User will be associated with each Essentials Permission Set, whose name matches exactly the name of a Microsoft Azure Active Directory Group to which that user belongs.
    • The Essentials User will be removed from each Essentials Permission Set, whose name does not match exactly the name of a Microsoft Azure Active Directory Group to which that user belongs.
    • The User will be associated with each Essentials Group, whose name matches exactly the name of a Microsoft Azure Active Directory Group to which that user belongs.
    • The Essentials User will be removed from each Essentials Group, whose name does not match exactly the name of a Microsoft Azure Active Directory Group to which that user belongs.
  • If the Microsoft Azure Active Directory user is locked out of Microsoft Azure Active Directory, the user will not be locked in Essentials database.
  • All the settings specified in the User Preferences, including Time Zone, System of Measure, Culture, and Language are assigned to new users.

Access the AD Synchronization Page

Procedure

In the Applications menu, select ADMIN > Operations Manager > AD Synchronization.
The AD Synchronization page appears.

AD Synchronization Workflow

This topic provides a basic workflow for using this module, as well as links to the available procedures, concepts, and reference topics.

Steps

  1. Create Azure AD Connection.
  2. Schedule an AD synchronization process to periodically update Essentials with user information from Microsoft Azure Active Directory.
    Important: After implementing AD synchronization, do not modify User information in Essentials; instead, modify the user information in Microsoft Azure Active Directory, and then synchronize. Synchronization overwrites all Essentials User site assignments, Permission Set assignments, group assignments and all other mapped information with the most recent information in Microsoft Azure Active Directory.

About Managing Users using AD Synchronization

About This Task

The AD integration feature is intended to simplify the Essentials user management process. It allows you to manage Essentials users through your existing, primary user management system: Microsoft Azure Active Directory.

User information may change periodically in Microsoft Azure Active Directory (e.g., group assignment, set assignment, site assignment, address, phone number, job title, etc.).

One advantage of configuring AD integration is the ability to synchronize Essentials User records with the information in Microsoft Azure Active Directory. The changes made in Microsoft Azure Active Directory will be reflected in Essentials after synchronization.

Note: AD integration is designed to ensure that these systems (Essentials and Microsoft Azure Active Directory) are synchronized. Always be sure to follow the recommended workflow for managing users.

Create Custom Roles

This task describes how to create roles additional to the baseline roles in Essentials.

Procedure

  1. In Active Directory, create the following hierarchy of groups:
    Parent Group
    • Group named after the custom permission set
      • Group named Custom Role
      • <user 1>
      • <user 2>
    To do so:
    1. Log in to AD.
    2. Access the groups page, and create a group named Custom Role.
    3. Create another group with the same name as the custom permission set that you want to create in Essentials.
    4. Access the parent group, and add the group that you have created in the previous step.
    5. In the groups page in AD, access the group that you have created in step 3, and add the Custom Role group.
      Note: The default values for language, Unit of Measurement (UOM) set, culture, and time zone are sourced from the Tenant Preferences. The default site value is determined from the AD sync page. If this value is not assigned, the default Predix site is used.
  2. Create a permission set with the same name as the custom role that you want to create in Essentials. When you do so, select the Custom Role check box under the Foundation category permission set.

Results

After the AD sync, the users and roles in AD will be created in Essentials. As needed, you can create groups in Essentials and assign them to the roles and users.

Site Filtering

About This Task

If you use a naming convention for your sites in Active Directory that is different from the naming convention in Essentials, you can use a regular expression to identify the site. The default naming convention expected in AD is <tenant ID>_<site name>.

Procedure

  1. In the Applications menu, select ADMIN > Operations Manager > AD Synchronization.
  2. In the Details section, in the Site Filter box, enter a regular expression in the following format: (?<Prefix>bp.us)\.(?<TenantIdentifier>[a-zA-Z0-9-]*)\.(?<SiteName>[^\s_]*)\.(?<Suffix>[^\s_]*)
    The following table describes the groups you can use in the regular expression:
    GroupDescription
    PrefixThis group is optional.
    Tenant IDThis group is required to uniquely identify the tenant when you use multiple tenants.
    Site NameThis group is required to uniquely identify the site.
    SuffixThis group is optional.
  3. Enter an example test string in the Site Filter Test String box, and then select Test.
    For example: bp.us.Tenant1.Site1.FeederShop
    A message appears, stating whether the site filter is valid.
  4. After entering a valid site filter, select Save.
    The site is identified, and after the AD sync, all the permission sets in the site in AD will be assigned to the site users in Essentials.

Create Azure AD Connection

Before You Begin

  • To initiate the sync, create a parent group such as Essentials.
  • Create the sub-groups which have the same name as the permission sets.
  • Assign, Create, or Modify the Essentials users in the sub-groups.
  • Any user under a group named as Administrator, will be a super user(Admin) in Essentials
  • Ensure that you have created, in Essentials, each site that you want to associate with users during synchronization.
  • In Microsoft Azure Active Directory, if needed, create groups whose name is <data source>_<site>, where:
    • <data source> is the name of the data source to which you will be connected during synchronization.
    • <site> is the exact name of a site in Essentials that you want to assign to some users during synchronization. It will not be assigned as the default site for the users.
    • If you want to assign all the sites in Essentials to a user then have a group in Microsoft Azure Active Directory named as <data source>_AllSites and assign Essentials user under it.
    Ensure that the Microsoft Azure Active Directory Group name matches the convention. For example, to assign users the site Plant, which exists in a data source named Industry, you would create a Microsoft AZure Active Directory Group named Industry_Plant.
    Note:
    • Each Essentials User must have a unique User ID. userPrincipalName in Microsoft Azure Active Directory field value will become the Essentials User ID for the user.
    • Any changes done in userPrincipalName in Microsoft Azure Active Directory will create a new user inEssentials as UserID is a unique identifier in Essentials.

Procedure

  1. Access the AD Synchronization Page.
  2. In the Azure Object ID box, enter the Directory ID of your Active Directory data.
  3. To connect to Azure AD,
    • In the Client ID box enter the client ID.
    • In the Client Secret box enter the client secret.
  4. In the Provider Name box, enter the name of the provider from where the users must be synchronized.
  5. In the Parent Group ID box, enter the ID of the parent group in AD, which contains all the permission sets as sub-groups and users.
  6. In Essentials, each User must be assigned to at least one site, and must be assigned to a default site. If you want the default site for each User to be set to a site during synchronization, then, in the Default Site box, select the site that should be set as the default site.
    Important:
    • To successfully log in to Essentials, Users must be assigned to at least one site, and must be assigned to a default site.
    • If your Essentials system contains only one site and you selected a default site in step 6, creating Microsoft Azure Active Directory Groups to map site assignments from Microsoft Azure Active Directory to Essentials is not required.
    • If no user-created site exists in the database, the Predix Default site will be assigned as the default site for each synchronized user.
  7. As needed, in the Field Mappings section, enter values in the available fields.
    In addition to the pre-configured mappings, you can map custom fields supported by Azure active directory with Human Resource fields in Essentials. To do so, enter the corresponding field names in the AD Field and APM Field boxes in the topmost row, and then select Add Field Mapping.
    The following fields are supported:
    • Manager
    • Hire date
    • OtherMails
    • BusinessPhones
    • EmployeeId
    The following fields are not supported:
    • Culture
    • ResourceID
    • Available?
    The Field Mappings section is populated automatically with AD baseline Field Mapping records.
  8. Select Save.
    The field mappings are created.

What To Do Next

Schedule an AD Synchronization Process.

Schedule an AD Synchronization Process

Procedure

  1. In the Applications menu, select ADMIN > Operations Manager > AD Synchronization.
  2. In the AD Synchronization workspace, in the AD Sync Job Scheduling section, select Add New Schedule or .
    The Edit Schedule window appears. Enter the values in the required fields. For more information on creating a schedule, see Schedule a Job.
  3. Select Save.
    The job schedule item is saved and appears in the AD Sync Job Scheduling section.

Results

  • When the job schedule item is active, the synchronization will be executed based on the defined schedule.
  • In case a user is not synched, check the Schedule logs.

User Status after AD Synchronization

About This Task

When the AD synchronization process runs, an Essentials User's status (i.e., whether the user is Active or not ) will be updated based upon various conditions in Microsoft Azure Active Directory) will be updated based upon various conditions in Microsoft Active Directory.
The Essentials user will not have any permission set when:
  • The Microsoft Azure Active Directory account for the user is deleted.
  • The user is not assigned to any Microsoft Azure Active Directory Groups.

Update an AD Domain Record

Procedure

  1. In the Applications menu, select ADMIN > Operations Manager > AD Synchronization.
  2. In the left pane, select the Domain record that you want to update.
    The workspace for the selected Domain record appears.
  3. As needed, update the values in the required text boxes.
  4. In the workspace, select .
    The changes to the domain record are saved.

Remove an AD Synchronization Job Schedule Item

Procedure

  1. In the Applications menu, select ADMIN > Operations Manager > AD Synchronization.
  2. In the AD Synchronization workspace, in AD Sync Job Scheduling section, beside the job schedule item that you want to remove, select .
    The AD Synchronization dialog box appears.
  3. Select Yes.
    The job schedule item is removed.