Account Inbox

Owned by Phillip Hanegan
Feb 29, 2024
6 min read

Because of the key role of Person objects in EmpowerID, the process by which EmpowerID joins inventoried accounts to these objects is foundational to how EmpowerID manages your user identities. As was mentioned in the Understanding Inventory topic, when EmpowerID inventories a resource system with user accounts, it does more than just write a copy of those user accounts to a table in the EmpowerID Identity Warehouse. It evaluates those accounts to determine whether or not they are owned by users, and based on that evaluation, it does one of the following three things:

  • It ignores them;

  • It joins them with existing EmpowerID Persons;

  • It provisions new EmpowerID Persons, joining those new Persons to the accounts.

The criteria for this evaluation is whether or not those inventoried accounts have valid FirstName and LastName properties (the properties are not null). If an account does not meet this criteria, EmpowerID simply ignores it and moves on to evaluate the next account. If an account does meet the criteria, EmpowerID marks the account as belonging to a user, captures all the unique identifier information for that account (SID, GUID, DN, UID, etc.), maps the account to the account store for attribute flow, and then executes a set of stored procedures, known as the "Join" and "Provision" rules. These rules, in conjunction with certain user-defined settings, tell EmpowerID what relationship, if any, it should create between inventoried user accounts and EmpowerID Persons. As a whole, this process of evaluating, joining, and provisioning is handled by what is known in EmpowerID as the "Account Inbox."

This process is dependent on the configuration of the Allow Automatic Provision Person on Inventory, Allow Automatic Person Join on Inventory, and Maximum Accounts Per Person settings for the account store containing the inventoried accounts. Accessible from the configuration screen for the account store, these settings tell EmpowerID what to do when it discovers new accounts during the inventory. The function of these settings is as follows:

  • Allow Automatic Person Join on Inventory  This setting tells EmpowerID whether it can join any new accounts discovered during the inventory process to an existing EmpowerID Person object with a matching attribute value specified by a join rule. If this setting is not enabled, EmpowerID will not join secondary accounts to an EmpowerID Person, but will instead provision new EmpowerID Person objects for each of those additional accounts.

  • Allow Automatic Provision Person on Inventory  This setting tells EmpowerID whether it should automatically provision an EmpowerID Person object for a newly discovered account. If this setting is not enabled, EmpowerID will add the new account to the Account table in the Identity Warehouse, but it will not provision a new Person to link to the account at inventory. Instead, the Person will be provisioned by the Account Inbox Processor in association with the Bulk Account Inbox permanent workflow, if enabled. If neither of those options are enabled, no Person objects will be provisioned.

  • Maximum Accounts Per Person  This setting tells EmpowerID how many accounts in a given account store can be associated with any one EmpowerID Person. This prevents the possibility of a runaway error caused by a wrongly configured Join rule.

How the Account Inbox Processes Accounts

As mentioned above, the Account Inbox is responsible for ensuring that each inventoried user account has a corresponding EmpowerID Person linked to it. Depending on how the account store is configured, accounts can be processed by the Account Inbox in one of two ways: They can be processed when discovered during inventory, or they can be processed in batches via the Bulk Account Inbox permanent workflow. Both methods achieve the same results; only the timing and the code executed by EmpowerID differ. Inventory provisioning uses a specific set of SQL stored procedures to process accounts as soon as they are added to the Account table in the EmpowerID Identity Warehouse, while the Bulk Account Inbox uses another set of SQL-stored procedures to batch process inventoried accounts. Of these two methods, unless immediate provisioning of EmpowerID Persons is required (within five minutes of inventory), using the Bulk Account Inbox permanent workflow to process accounts is recommended as it offers better performance for organizations with larger user bases and is easier to customize.

As the Bulk Account Inbox is the preferred method for processing accounts, we discuss the Account Inbox from that perspective. The Inventory Account Inbox functions in the same manner, with the only difference being the accounts are processed in total at inventory rather than in scheduled batches.

Bulk Account Inbox Processing Flow

The Bulk Account Inbox is a permanent workflow that, when enabled, runs in a continuous loop (once every 10 minutes), claiming and processing all previously unprocessed accounts in the Account table of the EmpowerID metadirectory. The processing flow for this workflow is as follows:

  1. The Account Inbox permanent workflow executes the Custom_Account_ClaimBulk stored procedure to evaluate all accounts where the value of the ProcessStatus field equals 0. This value tells the Account Inbox that the account is new and has yet to be evaluated. Once claimed, all accounts are added to a temporary EmpowerID view called the AccountInbox view. Once added to the AccountInbox view, the Account Inbox selects the first 1000 accounts and evaluates them for the following conditions:

    • The ProcessStatus field on the account is 0, meaning the account has not yet been processed

    • The PersonID field on the account is null, meaning the account does not belong to an EmpowerID Person

    • The Deleted field on the account is 0, meaning the account has not been previously deleted in EmpowerID

    • The CreatedDate field on the account is less than the current date

    • The FirstName field on the account is not null

    • The LastName field on the account is not null

    If an account meets all of the above conditions (each evaluates to true), the ProcessStatus field for that account is set to 1, and the Account Inbox applies the Join rules set for the account store to that account. If an account does not meet the above conditions, the ProcessStatus for that field is set to 2, meaning that the account has already been processed. This value ensures that the next time the Account Inbox tries to claim that account, the Custom_Account_ClaimBulk stored procedure will not return it.

  2. The Account Inbox then executes the Custom_Account_InboxJoinBulk stored procedure against each account passing the above Claim rules, meaning the account is a user account. This procedure looks to see if an account can be joined to an existing EmpowerID Person based on the Join rules (specific attribute matches between the two) set for the account store. By default, these Join rules look matching LastName and FirstName attributes as well as one of the following:

    • The value of the EmployeeID field on the account record matches the value of the PersonID field on the Person record.

    • The value of the DateOfBirth field on the account record matches the value of the DateOfBirth field on the Person record.

    • The value of the PersonalEmail field on the account record matches the value of the PersonalEmail field on the Person record.

    • The value of the Email field on the account record matches the value of the Email field on the Person record.

      If an account meets the conditions of one of the four above Join rules (or the conditions of any Join rules you customize), the Account Inbox joins the account to the qualifying EmpowerID Person. When this occurs, the PersonID field on the joined account is set to that of the PersonID field on the joined Person object, the ProcessStatus field is set to 2, and the AccountInboxResultID field is set to 1 (indicating "Success").

  3. The Account Inbox then executes the Custom_Account_InBoxGetAccountsToProvision stored procedure against each account passing the above Claim rules, where the value of the ProcessStatus field is not 2 (meaning the account is not currently joined to a Person). This stored procedure provisions a new EmpowerID Person for each user account currently not joined to one (the PersonID field on the account is null) and joins the two together. When this occurs, the PersonID field on the joined account is set to that of the PersonID field on the newly joined Person object, the ProcessStatus field is set to 2, and the AccountInboxResultID field is set to 1 (indicating "Success").

    • The value of the EmployeeID field on the account record matches the value of the PersonID field on the Person record.

    • The value of the DateOfBirth field on the account record matches the value of the DateOfBirth field on the Person record.

    • The value of the PersonalEmail field on the account record matches the value of the PersonalEmail field on the Person record.

    • The value of the Email field on the account record matches the value of the Email field on the Person record.

    If an account meets the conditions of one of the four above Join rules (or the conditions of any Join rules you customize), the Account Inbox joins the account to the qualifying EmpowerID Person. When this occurs, the PersonID field on the joined account is set to that of the PersonID field on the joined Person object, the ProcessStatus field is set to 2, and the AccountInboxResultID field is set to 1 (indicating "Success"). Additionally, if the Provision rule determines that a new EmpowerID Person object should be created, EmpowerID triggers the application of your Resource Entitlement or Provisioning policies to grant any additional user accounts or other resources, such as mailboxes or home folders, to which the user is entitled.

From a high level, this process can be represented by the following image: