Skip to end of banner
Go to start of banner

Universal Connector Integration Details

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

EmpowerID provides a Universal Connector that can be used for inventorying and managing resources originating in account stores for which EmpowerID does not provide a specific out of the box connector, like HR systems and custom applications via an Universal Connector database. (EmpowerID currently has out-of-the-box connectors for Active directory, LDAP, Google Apps, Office 365, and others). Using the Universal Connector requires the data in your external system be imported into the Universal Connector database via the technology of your choice—including scripting, an ETL tool like Microsoft SSIS, or code in the language of their choice—according to the schema defined for it by EmpowerID.

To find this topic helpful, you should have a good understanding of SQL and database principles.

Inbound Data

EmpowerID provides the following tables for importing data from an external system to the Universal Connector database. These tables are as follows:

User Table

FieldData TypeMax Length (Bytes)OptionalDefaultDescription
UserGUIDuniqueidentifier16No(newid())Uniquely identifies a user account in EmpowerID. If this field is blank, EmpowerID will generate the guid. This field should never be updated for the life of the record.
UserIDnvarchar(200)400No
Specifies the UserID for a user in the external system. This value is derived from the external system and must be unique for each user. This field should never be deleted or updated for the life of the record.
LogonNamenvarchar(200)400No
Specifies the logon name for the user account. This value must be unique for each user and can be set to any desired value, such as a user's EmployeeID contained within an external system or a combination of data that can be found, derived or calculated from an external system. If this field is blank, EmpowerID will generate a unique logon name for each user record.
Activebit1No((1))Specifies whether a user is active. This field can be used in place of the Status field.
FriendlyNamenvarchar(255)510Yes
Specifies the name shown to users in EmpowerID user interfaces. The field maps to the DisplayName attribute in Active Directory.
Namenvarchar(255)510Yes
Specifies the account name. This value should be unique and maps to the CNor DistinguishedName in Active Directory.
FirstNamenvarchar(50)100Yes
Specifies the first name of the user and maps to the givenName attribute in Active Directory.
MiddleNamenvarchar(50)100Yes
Specifies the middle name of the user and maps to the middleName attribute in Active Directory.
LastNamenvarchar(50)100Yes
Specifies the last name of the user. Maps to the LastName field in Active Directory.
Emailnvarchar(255)510Yes
Specifies the email address of the user. The value of this field can be used to set the email address of the user in Exchange when an Exchange Resource Entitlement exists. Additionally, this field is used by EmpowerID to determine whether the specific user account needs to be joined to an EmpowerID Person. For more information, see Overview of the Account Inbox.
EmployeeIDnvarchar(50)100Yes
Specifies the Employee ID of the user in the external system and will set the EmployeeID attribute of the user in Active Directory. When used, this value must be unique for each user. Additionally, this field is used by EmpowerID to determine whether the specific user account needs to be joined to an EmpowerID Person. For more information, see Overview of the Account Inbox.
BusinessRoleIDnvarchar(200)400Yes

Specifies the Business Role ID of the Business Role associated with the user in EmpowerID. When populating Business Role data, you can elect to set this field or the BusinessRoleName field. If BusinessRoleID is selected, this field will be set to the ID of the corresponding Business Role in the Business Role table of the EmpowerID Identity Warehouse. If the user does not have a Business Role, both fields can be left blank. If the user has more than one Business Role and Location, the UserBusinessRoleLocation table can used instead of, or in conjunction with, this field as EmpowerID performs a union of the Business Role and Location data in the User table and the Business Role and Location data in the UserBusinessRoleLocation table.


If this field is left blank and multiple entries exist in the UserBusinessRoleLocation table for a specific user, the record with the lowest priority will be set as the primary Business Role. 

EmpowerID uses this information for the following processes: 

  • RBAC: People belong to mapped Business Roles and Locations.
  • Role and Location Compiler and Role and Location Processor Jobs: These jobs will change a Person's primary Business Role and Location, as well as remove secondary Locations based on Business Role and Location mappings.
BusinessRoleNamenvarchar(200)400Yes

Specifies the Business Role Name of the Business Role associated with the user in EmpowerID. When populating Business Role data, you can elect to set this field or the BusinessRoleID field. If BusinessRoleName is selected, this field will be set to the name of the corresponding Business Role in the Business Role table of the EmpowerID Identity Warehouse. If the user does not have a Business Role, both fields can be left blank. If the user has more than one Business Role and Location, the UserBusinessRoleLocation table can used instead of, or in conjunction with, this field as EmpowerID performs a union of the Business Role and Location data in the User table and the Business Role and Location data in the UserBusinessRoleLocation table.


If this field is left blank and multiple entries exist in the UserBusinessRoleLocation table for a specific user, the record with the lowest priority will be set as the primary Business Role. 

EmpowerID uses this information for the following processes: 

  • RBAC: People belong to mapped Business Roles and Locations.
  • Role and Location Compiler and Role and Location Processor Jobs: These jobs will change a Person's primary Business Role and Location, as well as remove secondary Locations based on Business Role and Location mappings.
LocationIDnvarchar(200)400Yes

Specifies the ID of the Location associated with the user in EmpowerID. When populating Location data, you can elect to set this field or the LocationNamefield. If LocationID is selected, this field will be set to the ID of the corresponding Location in the Location table of the EmpowerID Identity Warehouse. If the user does not have a Location, both fields can be left blank. If the user has more than one Location, the UserBusinessRoleLocation table can used instead of, or in conjunction with, this field as EmpowerID performs a union of the Business Role and Location data in the User table and the Business Role and Location data in the UserBusinessRoleLocation table.


If this field is left blank and multiple entries exist in the UserBusinessRoleLocation table for a specific user, the record with the lowest priority will be set as the primary Location. 

EmpowerID uses this information for the following processes: 

  • RBAC: People belong to mapped Business Roles and Locations.
  • Role and Location Compiler and Role and Location Processor Jobs: These jobs will change a Person's primary Business Role and Location, as well as remove secondary Locations based on Business Role and Location mappings.
LocationNamenvarchar(200)400Yes

Specifies the name of the Location associated with the user in EmpowerID. When populating Location data, you can elect to set this field or the LocationID field. If LocationName is selected, this field will be set to the name of the corresponding Location in the Location table of the EmpowerID Identity Warehouse. If the user does not have a Location, both fields can be left blank. If the user has more than one Location, the UserBusinessRoleLocation table can used instead of, or in conjunction with, this field as EmpowerID performs a union of the Business Role and Location data in the User table and the Business Role and Location data in the UserBusinessRoleLocation table.


If this field is left blank and multiple entries exist in the UserBusinessRoleLocation table for a specific user, the record with the lowest priority will be set as the primary Location. 

EmpowerID uses this information for the following processes: 

  • RBAC: People belong to mapped Business Roles and Locations.
  • Role and Location Compiler and Role and Location Processor Jobs: These jobs will change a Person's primary Business Role and Location, as well as remove secondary Locations based on Business Role and Location mappings.
ManagerLogonNamenvarchar(200)400Yes
Specifies the LogonName of the user's manager, if any. If populated, the field will be used to set the user's direct manager in EmpowerID. When populating user manager data, you can elect to set this field or the ManagerAccountIDfield. If the user does not have a manager, both fields can be left blank.
ManagerAccountIDnvarchar(200)400Yes
Specifies the User ID of the user's manager, if any. If populated, the field will be used to set the user's direct manager in EmpowerID. When populating user manager data, you can elect to set this field or the ManagerLogonNamefield. If the user does not have a manager, both fields can be left blank.
Telephonenvarchar(50)100Yes
Specifies the primary telephone number of the user's place of business and and maps to the telephoneNumber attribute in Active Directory.
MobileNumbernvarchar(50)100Yes
Specifies the mobile number of the user and maps to the mobile attribute in Active Directory.
BusinessPhonenvarchar(50)100Yes
Specifies the business telephone number of the user.
HomePhonenvarchar(50)100Yes
Specifies the home telephone number of the user and maps to the homePhone attribute in Active Directory.
StreetAddressnvarchar(255)510Yes
Specifies the street address of the user and maps to the streetAddress attribute in Active Directory.
StreetAddress2nvarchar(255)510Yes
Specifies a secondary street address of the user.
Citynvarchar(100)200Yes
Specifies the city where the user is located and maps to the l attribute in Active Directory.
Statenvarchar(100)200Yes
Specifies the state where the user is located and maps to the st attribute in Active Directory.
Countrynvarchar(50)200Yes
Specifies the country where the user is located and maps to the co attribute in Active Directory.
Provincenvarchar(100)200Yes
Specifies the province where the user is located.
Companynvarchar(256)512Yes
Specifies the user's company name and maps to the company attribute in Active Directory.
Departmentnvarchar(256)512Yes
Specifies the user's department name and maps to the department attribute in Active Directory.
DepartmentNumbernvarchar(50)100Yes
Specifies the user's department number and maps to the departmentNumber attribute in Active Directory.
OfficeLocationnvarchar(450)900Yes
Specifies the location or address of the user's office and maps to the physicalDeliveryOfficeName attribute in Active Directory.
Locationnvarchar(450)900Yes
Specifies the user's location within an organization, such as their office number and maps to the location attribute in Active Directory.
Divisionnvarchar(450)900Yes
Specifies the user's division and maps to the division attribute in Active Directory.
PersonalTitlenvarchar(255)510Yes
Specifies the user's personal title, such as "Mr", "Mrs" or "Ms." This field maps to the personalTitle attribute in Active Directory
Descriptionnvarchar(255)510Yes
Specifies a description for the user and maps to the description attribute in Active Directory.
SecondLastNamenvarchar(50)100Yes
Specifies a second last name for the user, where such is used.
GenerationalSuffixnvarchar(10)20Yes
Specifies a generational suffix for the user, such as "JR" or "SR." This field maps to the generationQualifier attribute in Active Directory.
Initialsnvarchar(6)12Yes
Specifies the user's initials and maps to the initials attribute in Active Directory.
BirthNamenvarchar(255)510Yes
Specifies the name given to the user at birth.
DisplayNamePrintablenvarchar(255)510Yes
Specifies the printable name for the user and maps to the displayNamePrintable attribute in Active Directory.
PreferredFirstNamenvarchar(50)100Yes
Specifies the preferred first name of the user.
PreferredLastNamenvarchar(50)100Yes
Specifies the preferred last name of the user.
JobTitlenvarchar(255)100Yes
Specifies the user's job title within an organization and maps to the titleattribute in Active Directory.
AboutMenvarchar(max)maxYes
Specifies user-defined demographic information about the user.
PreferredLanguagenvarchar(50)100Yes
Specifies the preferred written or spoken language of the user. If this value is set on the person, then EmpowerID displays its user interfaces to that user in that language when localization is applied.
PostOfficeBoxnvarchar(50)100Yes
Specifies the post office box for the user and maps to the postOfficeBoxattribute in Active Directory.
SocialSecurityNumbernvarchar(50)100Yes
Specifies the social security number for the user. Please not that EmpowerID does not mask these characters. It is up to you to mask this or just include the last four digits if not.
NationalIdentificationNumbernvarchar(50)100Yes
Specifies the national identification number for the user.
CarLicensenvarchar(50)100Yes
Specifies the vehicle license or registration plate of the user's vehicle. This field maps to the carLicense attribute in Active Directory.
Ethnicitynvarchar(50)100Yes
Specifies the ethnicity of the user.
Gendernvarchar(15)30Yes
Specifies the gender of the user.
Districtnvarchar(256)512Yes
Specifies the district of the user.
Assistantnvarchar(450)900Yes
Specifies an assistant to the user.
PhotoUrlnvarchar(256)512Yes
Specifies the location of the user's photo.
IMAddressnvarchar(256)512Yes

SIPAddressnvarchar(256)512Yes

IdentityURLnvarchar(256)512Yes

URLPersonalnvarchar(256)512Yes
Specifies a person URL for the user.
URLBusinessnvarchar(256)512Yes
Specifies the business URL for the user.
URLOWAnvarchar(256)512Yes
Specified the OWA URL for the user.
Pagernvarchar(50)512Yes
Specifies the pager number for the user.
IpPhonenvarchar(50)100Yes
Specifies the user's IP phone number.
Faxnvarchar(50)100Yes
Specifies a fax number for the user.
Notesnvarchar(1024)100Yes
Field for inserting notes.
DateOfBirthdatetime8Yes
Specifies the date of birth for the user.
CityOfBirthnvarchar(50)100Yes
Specifies the city of birth for the user.
CountryOfBirthnvarchar(50)100Yes
Specifies the country of birth for the user.
EmployeeIDOthernvarchar(50)100Yes
Specifies an alternative Employee ID for the user.
EmployeeTypenvarchar(50)100Yes
Specifies the user's employee type.
ExtensionAttribute1nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute2nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute3nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute4nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute5nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute6nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute7nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute8nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute9nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute10nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute11nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute12nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute13nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute14nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute15nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute16xmlmaxYes
Can be used for setting a unique attribute value.






ExtensionAttribute24nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute25nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute26nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute27nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
Aliasnvarchar(100)200Yes

TargetAddressnvarchar(255)510Yes

Deletedbit1No((0))
Specifies whether a user has been deleted in the external system. DO NOT delete the record from the table. If the record no longer exists in the external system, then you can set this value to true.

If the user has been deleted, the LogonName will need to be updated if the same values might be reused later by a new user.

DeletedDatedatetime8Yes
Specifies the date and time when the user was deleted from the external system. For information purposes only.
TerminationDatedatetime2048Yes
Specifies the date and time when the user was terminated from a hired condition.
Disabledbit1No((0))
LockedOutbit1No((0))
LockedOutTimebigint8Yes

ExpiresOndatetime8Yes

ValidFromdatetime8Yes

ValidUntildatetime8Yes

PasswordNeverExpiresbit1No((0))Specifies whether the user's password is set to never expire.
CannotChangePasswordbit1No((0))Specifies whether the user can change their password.
PasswordExpiresdatetime8Yes
Specifies the date and time a user's password expires.
PasswordLastChangeddatetime8Yes
Specifies the date and time the user last changed their password.
MustChangePasswordAtNextLogonbit1No((0))Specifies whether the user must change their password the next time they log in to the system.
RequiresSmartCardForInteractiveLogonbit1No((0))
EnableSyncPasswordbit1No((1))Specifies whether EmpowerID will synchronize the password set on the user's Person object back to the account for the user in the external system. This setting does not affect Active Directory or any other type of "downstream" identity store. password for that user in the external system, if applicable. This has no correlation to any account Flag that controls if EmpowerID will reset the password for that account in reset password workflows. Set to false to prevent password resets to flow to this account.
DoNotAllowDeletebit1No((0))Specifies whether the user can be deleted in EmpowerID workflows.
LastLogonTimedatetime8Yes

Statusnvarchar(50)100Yes
Used to specify the condition of the user in an external system, such as whether they are in a "pre-hire" condition, full-standing, on leave or terminated. This field can be used to invoke other logic in EmpowerID, such as triggering RET policies that provision and deprovision resources like Exchange mailboxes, etc.
SecurityIdentifiernvarchar(255)510Yes
Specifies the unique value used to identity the user account and maps to the securityIdentifier attribute in Active Directory.
SIDnvarchar(255)510Yes
Specifies the unique value that identifies the user as a security principle. This field maps to the objectSid attribute in Active Directory.
DistinguishedNamenvarchar(2048)4096Yes
Specifies the location of the user object in the external system.
UserPrincipalNamenvarchar(255)510Yes
Specifies the UPN of the user.
ProfilePathnvarchar(450)900Yes
Specifies the path to the user's profile and maps to the profilePath attribute in Active Directory.
LogonScriptnvarchar(450)900Yes
Specifies the logon script to run for the user, if any.
HomeDirectorynvarchar(450)900Yes
Specifies the home directory for the user account and maps to the homeDirectory attribute in Active Directory.
HomeDrivenvarchar(5)10Yes
Specifies the drive letter to which to map the UNC path set for HomeDirectory. This field maps to the homeDrive attribute in Active Directory.
AllowDialinbit1Yes
Specifies whether the user can connect remotely.
HideInEmpowerIDbit1No((0))Specifies whether the account will be hidden from most views in EmpowerID.
AllowJoinbit1No((1))Specifies whether EmpowerID will join the user account to an EmpowerID Person.
AllowProvisionbit1No((1))Specifies whether EmpowerID will provision a new EmpowerID Person for the user account upon inventory.
ConfigurationXmlxmlmaxYes
Extensibility field. Reserved.
SystemChangedDatedatetime8Yes
This field is optional. It is meant to help you track changes to records in the external system.

A best practice for writing code to synchronize these tables is to compare the ID field of the object and the SystemChangedDate field in this table and comparing them with the value of those fields in the external system. If it is discovered that the SystemChangedDate in the external system is greater, then those records should be synced.

CreatedDatedatetime8No(getutcdate())This field is auto-populated with the UTC time corresponding to the date and time the user record is created.
ChangedTimetimestamp8No

This field is time-stamped corresponding to the time any values associated with the user record are modified. This field should not be manually updated or inserted.

When EmpowerID initially inventories the records in the tables of the Universal Connector database, it pulls all the data it discovers there into the EmpowerID Identity Warehouse, provisioning the appropriate business objects therein. Then on subsequent inventory calls, EmpowerID checks the ChangedTime field on those records to see if the value of that field is greater than the last time inventory ran. If the value is greater, EmpowerID updates the corresponding record for that object in the EmpowerID Identity Warehouse.

Group Table

FieldData TypeMax Length (Bytes)OptionalDefaultDescription
GroupGUIDuniqueidentifier16No(newid())Uniquely identifies a group in EmpowerID. If this field is blank, EmpowerID will generate the guid. This field should never be updated for the life of the record
GroupIDnvarchar(200)400No
Specifies the ID for group from the external system. The value of this field must be unique for each group. This field should never be deleted or updated for the life of the record.
LogonNamenvarchar(200)400No
Specifies the group LogonName. The value of this field should be unique.
Namenvarchar(200)400Yes
Specifies the name of the group. This value should be unique.
FriendlyNamenvarchar(255)510Yes


Specifies the name of the group shown to users in EmpowerID user interfaces.
Descriptionnvarchar(max)maxYes
Specifies a description for the group.
IsMailEnabledbit1No((0))Specifies whether the group is mail-enabled.
Emailnvarchar(100)512Yes
Specifies the email address for the group.
MailNickNamenvarchar(256)512Yes

Notesnvarchar(max)maxYes

ExtensionAttribute1nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute2nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute3nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute4nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute5nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute6nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute7nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute8nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute9nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute10nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute11nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute12nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute13nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute14nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute15nvarchar(1024)2048Yes
Can be used for setting a unique attribute value.
ExtensionAttribute16xmlmaxYes
Can be used for setting a unique attribute value.
ExtensionAttribute17varbinary(max)maxYes
Can be used for setting a unique attribute value.
ExtensionAttribute18varbinary(max)maxYes
Can be used for setting a unique attribute value.
ExtensionAttribute19bit1Yes
Can be used for setting a unique attribute value.
ExtensionAttribute20bit1Yes
Can be used for setting a unique attribute value.
ExtensionAttribute21bit1Yes
Can be used for setting a unique attribute value.
ExtensionAttribute22bit1Yes
Can be used for setting a unique attribute value.
Deletedbit1No((0))
Specifies whether the group has been deleted. DO NOT delete the record from the table.

If the group has been deleted, the LogonName will need to be updated if the same values might be reused for a new group later.

DeletedDatedatetime8Yes
Specifies the date and time when the group was deleted. For information purposes only.
DoNotAllowDeletebit1No((0))Specifies whether the group can be deleted in EmpowerID workflows.
AllowJoinRequestsbit1No((1))Specifies whether the group will be visible in workflows that allow users to request group membership. Also specifies whether the group appears in the IT Shop as a requestable resource.
AutoAcceptJoinLeaveRequestsbit1No((0))Specifies whether users can join or leave the group without requiring access permission to the JoinGroup or LeaveGroup workflows.
HIdeInEmpowerIDbit1No((0))Specifies whether the group will be hidden in most EmpowerID views.
HIdeMembershipbit1No((0))Specifies whether group membership will be hidden in most EmpowerID views.
IsHighSecurityGroupbit1No((0))Specifies whether the group is a high security group. If true, the group will be flagged and appear in some reports and SetGroups as such.
ValidFromdatetime8Yes

ValidUntildatetime8Yes

DistinguishedNamenvarchar(2048)4096Yes
Specifies the location of the group in the external system.
ConfigurationXmlxmlmaxNo((1))Extensibility field. Reserved.
SystemChangedDatedatetime8Yes
This field is optional. It is meant to help you track changes to records in the external system.

A best practice for writing code to synchronize these tables is to compare the ID field of the object and the SystemChangedDate field in this table and comparing them with the value of those fields in the external system. If it is discovered that the SystemChangedDate in the external system is greater, then those records should be synced.

CreatedDatedatetime8Yes
This field is auto-populated with the UTC time corresponding to the date and time the record is created.
ChangedTimetimestamp8No(getutcdate())

Auto-populated timestamp corresponding to the time a modification occurs to the group. Do not update or insert.


When EmpowerID initially inventories the records in the tables of the Universal Connector database, it pulls all the data it discovers there into the EmpowerID Identity Warehouse, provisioning the appropriate business objects therein. Then on subsequent inventory calls, EmpowerID checks the ChangedTime field on those records to see if the value of that field is greater than the last time inventory ran. If the value is greater, EmpowerID updates the corresponding record for that object in the EmpowerID Identity Warehouse.

Location Table

This table is used to manage location information. Each record inserted into the table is represented as an external location in EmpowerID. The schema for this table allows organizations to insert data to represent all possible locations to which users can belong within the organization, including departments, divisions, geographical sites, org charts and functional areas. As with the Business Role table, each location inserted into the table can be mapped to an EmpowerID Location. Assigning users to one or more locations in this table assigns to those users to one or more locations in EmpowerID according to the mapping rules set for those locations.

In order to avoid resource-intensive calls to the EmpowerID synchronization engine, the records in this table should only be updated when a change occurs to those records in the external system.


FieldData TypeMax Length (Bytes)OptionalDefaultDescription
LocationGUIDuniqueidentifier16No(newid())Uniquely identifies a location in EmpowerID. If this field is blank, EmpowerID will generate the guid. This field should never be updated for the life of the record
LocationIDnvarchar(200)400No
Specifies the ID for location in the external system. The value of this field must be unique for each location. This field should never be deleted or updated for the life of the record.
Namenvarchar(200)400Yes
Specifies the name of the location. This value should be unique.
ParentLocationIDnvarchar(200)400Yes
Specifies the ID of the location's parent. If populated, this sets the location parent in EmpowerID. When populating the parent of a location, you can elect to use this field or the ParentName field. If the location does not have a parent, both fields can be left empty.
ParentNamenvarchar(200)400Yes
Specifies the name of the location's parent. If populated, this sets the location parent in EmpowerID. When populating the parent of a location, you can elect to use this field or the ParentLocationID field. If the location does not have a parent, both fields can be left empty.
FriendlyNamenvarchar(255)510Yes


Specifies the name of the location shown to users in EmpowerID user interfaces.
Descriptionnvarchar(512)1024Yes
Specifies a description for the location.
ExtensionAttribute1nvarchar(500)1000Yes
Can be used for setting a unique attribute value.
ExtensionAttribute2nvarchar(500)1000Yes
Can be used for setting a unique attribute value.
ExtensionAttribute3nvarchar(500)1000Yes
Can be used for setting a unique attribute value.
ExtensionAttribute4nvarchar(500)1000Yes
Can be used for setting a unique attribute value.
ExtensionAttribute5nvarchar(500)1000Yes
Can be used for setting a unique attribute value.
ExtensionAttribute6nvarchar(500)1000Yes
Can be used for setting a unique attribute value.
ExtensionAttribute7nvarchar(500)1000Yes
Can be used for setting a unique attribute value.
ExtensionAttribute8nvarchar(500)1000Yes
Can be used for setting a unique attribute value.
ExtensionAttribute9nvarchar(500)1000Yes
Can be used for setting a unique attribute value.
ExtensionAttribute10nvarchar(500)1000Yes
Can be used for setting a unique attribute value.
ExtensionAttribute11nvarchar(max)maxYes
Can be used for setting a unique attribute value.
ExtensionAttribute12nvarchar(max)maxYes
Can be used for setting a unique attribute value.
ExtensionAttribute13xmlmaxYes
Can be used for setting a unique attribute value.
ExtensionAttribute14varbinary(max)maxYes
Can be used for setting a unique attribute value.
ExtensionAttribute15varbinary(max)maxYes
Can be used for setting a unique attribute value.
Deletedbit1No((0))
Specifies whether the location has been deleted in the external location. DO NOT delete the record from the table.

If the location has been deleted, the Name field will need to be updated if the same values might be reused for a new location later.

DeletedDatedatetime8Yes
Specifies the date and time when the location was deleted. For information purposes only.
IsAssignablebit1No((1))Specifies whether the location can be selected from the Location trees in EmpowerID. Set to false if you do not want users to be assigned to the Location.
ShowInTreebit1No((1))Specifies whether the location appears in the Location trees in EmpowerID.
ConfigurationXmlxmlmaxNo((1))Extensibility field. Reserved.
SystemChangedDatedatetime8Yes
This field is optional. It is meant to help you track changes to records in the external system.

A best practice for writing code to synchronize these tables is to compare the ID field of the object and the SystemChangedDate field in this table and comparing them with the value of those fields in the external system. If it is discovered that the SystemChangedDate in the external system is greater, then those records should be synced.

CreatedDatedatetime8Yes(getutcdate())This field is auto-populated with the UTC time corresponding to the date and time the record is created.
ChangedTimetimestamp8No
Auto-populated timestamp corresponding to the time a modification occurs to the location. Do not update or insert.

When EmpowerID initially inventories the records in the tables of the Universal Connector database, it pulls all the data it discovers there into the EmpowerID Identity Warehouse, provisioning the appropriate business objects therein. Then on subsequent inventory calls, EmpowerID checks the ChangedTime field on those records to see if the value of that field is greater than the last time inventory ran. If the value is greater, EmpowerID updates the corresponding record for that object in the EmpowerID Identity Warehouse.

Business Role Table

This table is used to manage Business Role information. Each record inserted into the table is represented as an External Business Role in EmpowerID that can be mapped to any EmpowerID Business Roles.

In order to avoid resource-intensive calls to the EmpowerID synchronization engine, the records in this table should only be updated when a change occurs to those records in the external system.


FieldData TypeMax Length (Bytes)OptionalDefaultDescription
BusinessRoleGUIDuniqueidentifier16No(newid())Uniquely identifies a Business Role in EmpowerID. If this field is blank, EmpowerID will generate the guid. This field should never be updated for the life of the record
BusinessRoleIDnvarchar(200)400No
Specifies the ID for Business Role. The value of this field must be unique for each Business Role. This field should never be deleted or updated for the life of the record.
Namenvarchar(200)400Yes
Specifies the name of the Business Role. This value should be unique.
ParentNamenvarchar(200)400Yes
Specifies the name of the Business Role's parent. If populated, this sets the Business Role parent in EmpowerID. When populating the parent of a Business Role, you can elect to use this field orthe ParentName field. If the Business Role does not have a parent, both fields can be left empty.
FriendlyNamenvarchar(255)510Yes


Specifies the name of the Business Role shown to users in EmpowerID user interfaces.
Descriptionnvarchar(512)1024Yes
Specifies a description for the Business Role.
ExtensionAttribute1nvarchar(500)1000Yes
Can be used for setting a unique attribute value.
ExtensionAttribute2nvarchar(500)1000Yes
Can be used for setting a unique attribute value.
ExtensionAttribute3nvarchar(500)1000Yes
Can be used for setting a unique attribute value.
ExtensionAttribute4nvarchar(500)1000Yes
Can be used for setting a unique attribute value.
ExtensionAttribute5nvarchar(500)1000Yes
Can be used for setting a unique attribute value.
ExtensionAttribute6nvarchar(500)1000Yes
Can be used for setting a unique attribute value.
ExtensionAttribute7nvarchar(500)1000Yes
Can be used for setting a unique attribute value.
ExtensionAttribute8nvarchar(500)1000Yes
Can be used for setting a unique attribute value.
ExtensionAttribute9nvarchar(500)1000Yes
Can be used for setting a unique attribute value.
ExtensionAttribute10nvarchar(500)1000Yes
Can be used for setting a unique attribute value.
ExtensionAttribute11nvarchar(max)maxYes
Can be used for setting a unique attribute value.
ExtensionAttribute12nvarchar(max)maxYes
Can be used for setting a unique attribute value.
ExtensionAttribute13xmlmaxYes
Can be used for setting a unique attribute value.
ExtensionAttribute14varbinary(max)maxYes
Can be used for setting a unique attribute value.
ExtensionAttribute15varbinary(max)maxYes
Can be used for setting a unique attribute value.
Deletedbit1No((0))Specifies whether the Business Role has been deleted. DO NOT delete the record from the table.
If the Business Role has been deleted, the Name will need to updated if the same values might be reused for a new Business Role later.
DeletedDatedatetime8Yes
Specifies the date and time when the Business Role was deleted. For information purposes only.
IsAssignablebit1No((1))Specifies whether the Business Role can be selected from the Business Role trees in EmpowerID. Set to false if you do not want users to be assigned to the Business Role.
ShowInTreebit1No((1))Specifies whether the Business Role appears in the Business Role trees in EmpowerID.
ConfigurationXmlxmlmaxNo((1))Extensibility field. Reserved.
SystemChangedDatedatetime8Yes
This field is optional. It is meant to help you track changes to records in the external system.
A best practice for writing code to synchronize these tables is to compare the ID field of the object and the SystemChangedDate field in this table and comparing them with the value of those fields in the external system. If it is discovered that the SystemChangedDate in the external system is greater, then those records should be synced.
CreatedDatedatetime8Yes(getutcdate())This field is auto-populated with the UTC time corresponding to the date and time the record is created.
ChangedTimetimestamp8No
Auto-populated timestamp corresponding to the time a modification occurs to the group. Do not update or insert.
When EmpowerID initially inventories the records in the tables of the Universal Connector database, it pulls all the data it discovers there into the EmpowerID metadirectory, provisioning the appropriate business objects therein. Then on subsequent inventory calls, EmpowerID checks the ChangedTime field on those records to see if the value of that field is greater than the last time inventory ran. If the value is greater, EmpowerID updates the corresponding record for that object in the EmpowerID metadirectory.
CreatedDatedatetime8Yes(getutcdate())This field is auto-populated with the UTC time corresponding to the date and time the record is created.
ChangedTimetimestamp8No
Auto-populated timestamp corresponding to the time a modification occurs to the location. Do not update or insert.

When EmpowerID initially inventories the records in the tables of the Universal Connector database, it pulls all the data it discovers there into the EmpowerID Identity Warehouse, provisioning the appropriate business objects therein. Then on subsequent inventory calls, EmpowerID checks the ChangedTime field on those records to see if the value of that field is greater than the last time inventory ran. If the value is greater, EmpowerID updates the corresponding record for that object in the EmpowerID Identity Warehouse.


UserGroup Table

This table is used to map users with multiple group entries. The data in this table should be synchronized with the state of information from the external system.

When changes to the objects in your external system originate in the external system, you should not remove and repopulate any data contained this table with new values as EmpowerID may be performing an inventory of the data during a moment when the table contains no information. If this occurs, EmpowerID could interpret that to mean that your users have been removed from their groups and will update any related records in EmpowerID to that end. It is best to use a strategy of syncing changes only.


When a user is added to or removed from a group, the ChangedTime field on the appropriate records in the User table of the Universal Connector database are updated. At the next inventory, EmpowerID detects the change and updates the corresponding records in the EmpowerID metadirectory.


FieldData TypeMax Length (Bytes)OptionalDefaultDescription
GroupIDnvarchar(200)400No
Specifies the GroupID for the group to which the user belongs.
UserIDnvarchar(200)400No
Specifies the UserID of the user belonging to the group.
CreatedDatedatetime8Yes(getutcdate())This field is auto-populated with the UTC time corresponding to the date and time the record is created.

UserBusinessRoleLocation Table

This table is used to associate users with Business Role and Location combinations. The data in this table can be used in conjunction with, or as a replacement for, the Business Role and Location fields in the User table as EmpowerID performs a union of the Business Role and Location data in the User table and the Business Role and Location data in the UserBusinessRoleLocation table.

When changes to the objects in your external system originate in the external system, you should not remove and repopulate any data contained this table with new values as EmpowerID may be performing an inventory of the data during a moment when the table contains no information. If this occurs, EmpowerID could interpret that to mean that your users have been removed from their Business Roles and Locations and will update any related records in EmpowerID to that end. It is best to use a strategy of syncing changes only.

Data populated in the UserBusinessRoleLocation table should not overlap with the Business Role and Location specified in the User table. Additionally, the priority specified in the UserBusinessRoleLocation table should be greater than 0.


When a user is added to or removed from a Business Role and Location, the ChangedTime field on the appropriate records in the User table of the Universal Connector database is updated. At the next inventory, EmpowerID detects the change and updates the corresponding records in the EmpowerID metadirectory.


FieldData TypeMax Length (Bytes)OptionalDefaultDescription
UserIDnvarchar(200)200No
Specifies the UserID of the user in the Business Role and Location.
BusinessRoleIDnvarchar(200)200No
Specifies the BusinessRoleID of the user's Business Role.
LocationIDnvarchar(200)200No
Specifies the LocationID of the user's location.
Priorityint4No((0))Used to help order the Business Role and Location combinations to which the user is associated. In EmpowerID this field can be used to help break ties between any Resource Entitlements, or Default Person Attributes where the policies which applies to the higher priority combination would be chosen.

Outbound Data

Once data has been imported into EmpowerID, you can use the bidirectional capabilities of the Universal Connector to write any changes occurring to that data in EmpowerID back to the originating system. The Universal Connector gives you two options for doing so:

  1. You can process the updates in real-time as they occur in EmpowerID. This is the recommended method.
  2. You can process the updates in batches.


The method by which EmpowerID handles change processing depends on the settings applied to the Universal Connector account store in the EmpowerID Management Console. See Connecting to Custom Directories in the EmpowerID Administrator's Guide for more information about these settings.

Real-time Processing

When using real-time processing, you will need to write a .NET module that references the TheDotNetFactory.Framework.Connectors.StandardConnector.dlland implements the IChangeLogProcessor interface. The IChangeLogProcessor provides methods that you can use to process any changes occurring to the state of your business objects against your backend systems.

The IChangeLogProcessor is provided as a reference example; however, any type of coding or scripting could be used to read the changes from the change log and execute them in the custom directory or application.


The IChangeLogProcessor provides the following methods:


MethodDescription
bool CreateBusinessRole(Dictionary<string, object> attributes, out string businessRoleID)This method is invoked when a new Business Role is created in EmpowerID. Should return true if successful. Parameters are as follows:
  • Attributes — Name/Value pair collection of properties the new Business Role should have. The following are minimally required:
    • Name — As entered in EmpowerID
    • BusinessRoleGUID — Unique ID in EmpowerID
  • businessRoleID — Outbound parameter that should return the uniqueID of the record created in the target system.
bool CreateGroup(Dictionary<string, object> attributes, out string GroupID)This method is invoked when a new group is created in EmpowerID. Should return true if successful. Parameters are as follows:
  • Attributes — Name/Value pair collection of properties the new group should have. The following are minimally required:
    • Name — As entered in EmpowerID
    • GroupGUID — Unique ID in EmpowerID
    • Any and all other properties (non-null) entered by the user during group creation
  • GroupID — Outbound parameter that should return the unique ID of the record created in the target system.
bool CreateUser(Dictionary<string, object> attributes, out string userID)This method is invoked when a new user is created in EmpowerID. Should return true if successful. Parameters are as follows:
  • Attributes — Name/Value pair collection of properties the new user should have. The following are minimally required:
    • Name — As entered in EmpowerID
    • UserGUID — Unique ID in EmpowerID
    • LogonName — As entered in EmpowerID
    • During RET Provisioning — Any and all attributes set for attribute flow (any direction)
    • Any and all other properties (non-null) entered by the user during account creation
  • UserID — Outbound parameter that should return the unique ID of the record created in the target system.
bool CreateLocation(Dictionary<string, object> attributes, out string locationID)This method is invoked when a new location is created in EmpowerID. Should return true if successful. Parameters are as follows:
  • Attributes — Name/Value pair collection of properties the new user should have. The following are minimally required:
    • Name — As entered in EmpowerID
    • locationGUID — Unique ID in EmpowerID
  • locationID — Outbound parameter that should return the unique ID of the record created in the target system.
bool DeleteBusinessRole(string businessRoleID)This method is invoked when a Business Role is deleted in EmpowerID. Should return true if successful. Parameters are as follows:
  • businessRoleID — Unique ID of the record to be deleted in the target system.
bool DeleteGroup(string groupID)This method is invoked when a group is deleted in EmpowerID. Should return true if successful. Parameters are as follows:
  • groupID — Unique ID of the record to be deleted in the target system.
bool DeleteUser(string userID)This method is invoked when a user is deleted in EmpowerID. Should return true if successful. Parameters are as follows:
  • userID — Unique ID of the record to be deleted in the target system.
bool DeleteLocation(string locationID)This method is invoked when a location is deleted in EmpowerID. Should return true if successful. Parameters are as follows:
  • locationID — Unique ID of the record to be deleted in the target system.
bool Disable(string userID)This method is invoked when a user becomes disabled in EmpowerID. Should return true if successful. Parameters are as follows:
  • userID — Unique ID of the record to be disabled in the target system.
bool Enable(string userID)This method is invoked when a previously disabled user becomes enabled in EmpowerID. Should return true if successful. Parameters are as follows:
  • userID — Unique ID of the record to be enabled in the target system.
bool ResetPassword(string userID, string password)This method is invoked when a user's password is reset in EmpowerID. Should return true if successful. Parameters are as follows:
  • userID — Unique ID of the user in the target system.
  • password — new password
bool RestoreGroup(string groupID)This method is invoked when a previously deleted group is restored in EmpowerID. Should return true if successful. Parameters are as follows:
  • groupID — Unique ID of the group to be restored in the target system.
bool RestoreUser(string userID)This method is invoked when a previously deleted user is restored in EmpowerID. Should return true if successful. Parameters are as follows:
  • userID — Unique ID of the user to be restored in the target system.
bool Unlock(string userID)This method is invoked when a previously locked out user is unlocked in EmpowerID. Should return true if successful. Parameters are as follows:
  • userID — Unique ID of the user to be unlocked in the target system.
bool UpdateBusinessRole(string businessRoleID, Dictionary<string, object> attributes)This method is invoked when one or more Business Role attributes are updated in EmpowerID. Should return true if successful. Parameters are as follows:
  • businessRoleID — Unique ID of the Business Role to be updated in the target system.
  • Attributes — Name/Value pair collection of the properties that have changed.
bool UpdateGroup(string groupID, Dictionary<string, object> attributes)This method is invoked when one or more group attributes are updated in EmpowerID. Should return true if successful. Parameters are as follows:
  • groupID — Unique ID of the group to be updated in the target system.
  • Attributes — Name/Value pair collection of the properties that have changed.
bool UpdateLocation(string locationID, Dictionary<string, object> attributes)This method is invoked when one or more location attributes are updated in EmpowerID. Should return true if successful. Parameters are as follows:
  • locationID — Unique ID of the Location to be updated in the target system.
  • Attributes — Name/Value pair collection of the properties that have changed.
bool UpdateUser(string userID, Dictionary<string, object> attributes)This method is invoked when one or more user attributes are updated in EmpowerID. Should return true if successful. Parameters are as follows:
  • userID — Unique ID of the user account to be updated in the target system.
  • Attributes — Name/Value pair collection of the properties that have changed.
bool RemoveFromGroup(List<string> userIDs, string groupID)This method is invoked when a user is removed from a group in EmpowerID. Should return true if successful. Parameters are as follows:
  • groupID — Unique ID of the group from which members are being removed.
  • userIDs — List of unique IDs of the users being removed from the group.
bool AddToGroup(string userID, string groupID)This method is invoked when a user is added to a group in EmpowerID. Should return true if successful. Parameters are as follows:
  • groupID — Unique ID of the group to which the user is being added.
  • userID — Unique ID of the user being added to the group.
bool SetGroupMembers(List<string> userIDs, string groupID)

This method is invoked when a group's membership is being explicitly/definitively set by EmpowerID. Should return true if successful. Parameters are as follows:

  • groupID — Unique ID of the group from which users are being removed.
  • userIDs — List of unique IDs of the users who should be part of the group (other users would presumable be removed).

Batch Processing

When the Universal Connector account store is set for batch processing, EmpowerID writes information about each change occurring to a business object via EmpowerID as a record in the ChangeLog table of the Universal Connector database.

To employ batch processing, you need to write application-specific code that reads from the ChangeLog table and process the data against your managed system.


The ChangeLog table contains the following fields:

FieldDescription
ChangeLogIDThis specifies the unique identifier for the change log event.
ObjectIDThis is the unique identifier (the object GUID) that corresponds to the changed object. This identifier is generated by EmpowerID for the object during inventory.
ChangeLogObjectTypeID

This specifies what type of object was changed as defined by the ChangeLogObjectType table of the Universal Connector database. This field can contain the following four values:

ChangeLogObjectTypeIDObject Type
1User
2Group
3Location
4Business Role
ChangeLogTypeID

This specifies what type of change occurred to the object as defined by the ChangeLogType table of the Universal Connector database. For each entry in the ChangeLog table, changes can be of one of the following types:

ChangeLogTypeIDNameDescription
1CreateSpecifies that the object was created in EmpowerID.
2UpdateSpecifies that one or more object attributes were edited in EmpowerID.
3DeleteSpecifies that the object was deleted in EmpowerID.
4ResetPasswordSpecifies that the user's password was reset in EmpowerID.
5EnableSpecifies that a previously disabled user account was disabled in EmpowerID.
6DisableSpecifies that a previously enabled user account was disabled in EmpowerID.
7AddToGroupSpecifies that the object was added to a group in EmpowerID.
8RemoveFromGroupSpecifies that the object was removed from a group in EmpowerID.
9SetGroupMembersContains a list of all users that should belong to a specific group.
10MoveSpecifies that the object was moved from one location to another in EmpowerID.
11UnlockSpecifies that a locked user account was unlocked in EmpowerID.
12RestoreSpecifies that a previously deleted object was restored in EmpowerID.
ChangeLogDataThis field contains an XML-formatted list any the change that occurred.
ProcessTimeThis is an optional field that can be used by developers to specify when a change event is processed by their system.
ProcessStatus

This is an optional field that can be used by developers to specify the status of the change event. 

The following status codes are suggested as these are the codes EmpowerID uses within its own system to indicate the status of an event; however, you are free to use other codes in addition to these or implement your own status scheme altogether.


  • 0 — The event was not processed. This is the default value.
  • 1 — The event has been claimed by a server, but the process has not yet completed. In the event multiple servers could process the change event, claiming prevents the change event from being processed by more than one server.
  • 2 — The event has been processed successfully.
  • 3 — An error occurred processing the event.
  • 4 — The event was ignored.
FailedCountThis is an optional field that can be used to specify the number of times a changed event has failed to process in a client application. Developers can use this data to perform certain tasks, such as firing a retry mechanism in their system.
LockedByServerThis is an optional field that can be used by developers to specify which server has claimed a change event. This field is useful in the event multiple servers could process the change event.
ModifiedDateSpecifies the date and time in UTC that an object was modified in EmpowerID.
ConfigurationXml
CreatedDateSpecifies the date and time in UTC that a change event was created in EmpowerID. As entries in the ChangeLog table are written chronologically based on the created date, it is suggested that developers use this field to process these changes against their systems ordered by oldest to newest CreatedDate.

Once you have developed your module, you will need to register the assembly in EmpowerID by updating the ChangeLogAdapterAssembly and the ChangeLogAdapterType fields for your organization's Universal Connector. You can do so by editing the resource system in the EmpowerID Web interface. To edit these fields, do the following: 

  1. From the Navigation Sidebar of the EmpowerID Web interface, expand Admin > Applications and Directories and click Account Stores and Systems.
  2. Click the Resource Systems tab and then locate your specific Universal Connector resource system.
  3. Click the Display Name link for the resource system.




  4. On the Resource System Details page that opens, click the Edit link.




  5. In the Edit page that opens, locate the ChangeLogAdapterAssemblyandChangeLogAdapterTypefields, update them appropriately and then clickSave.



    Please note that these fields must contain the name of your assembly and the namespace-qualified name of the assembly and the assembly type, respectively.


In this article


  • No labels