Create Custom Attribute Flow Handlers

By default, EmpowerID retrieves attribute values for each user account in a connected account store and maps them value for value to the corresponding Person attributes stored in the EmpowerID Identity Warehouse. However, you can create your own Attribute Flow Handlers to translate the native value of an attribute from one system to the value that should be set for that attribute in another system. The easiest and recommended way to do this is to create a class library in Workflow Studio that inherits from the default Attribute Flow Handler that ships with EmpowerID and overriding the methods of the base DefaultAttributeFlowHandler class with your custom logic. Notable methods involved with attribute flow include those in the table below.

Of the methods listed, GetValueForPerson() and GetValueForAccount() are the only methods you need to override when transforming Person attributes to account attributes.

Method

Description

Parameters

Comments

Method

Description

Parameters

Comments

GetValueForPerson

This method is used to compare the current value of a specified attribute on an EmpowerID identity entry record with the equivalent property on the corresponding EmpowerID Person record.

 

  • accountStoreIdentityEntry – Current working copy of the identity entry related to the person

  • person – Current person being processed (usually for reference only)

  • objectAttributeSync – Current attribute/property being processed

Parameters should not be changed

  • This method is called during inventory and inbox/outbox processing.

  • Returns a string value. If the values between the identity entry and the corresponding Person record differ, an outbox or inbox entry may be created (based on the Attribute Flow rules set for the account store); if the values are equal, no further processing occurs.

  • Can be overridden for translation of the value in the external system to an EmpowerID native value.

GetValueForAccount

This method is used to compare the current attribute value on an EmpowerID Person to the equivalent property on the identity entry.

  • accountStoreIdentityEntry – Current working copy of the identity entry related to the person

  • person – Current person being processed (usually for reference only)

  • objectAttributeSync – Current attribute/property being processed

Parameters should not be changed

  • This method is called during inventory and inbox/outbox processing.

  • Returns a string representation of the value to be applied on the identity entry.

  • The value returned is recorded as an outbox entry that will be created if the person and the identity entry properties do not match and flow rules prescribe an outbound flow.

  • When the Attribute Flow processor updates the identity entry, the string is converted to the native data type for that property. This transformation occurs in the account store’s identity entry provider.

SetPersonAttribute

This method is used to apply changes that have occurred to Attribute Inbox records to the corresponding Person record.

  • person – Person record to be updated

  • attributeInbox – Inbox entry of the change to be processed

  • This method is called by the Attribute Flow Processing job while processing inbox entries.

  • Returns true if the attribute changes was successfully applied to the Person record; otherwise, returns false. Returned value is recorded in the ProcessStatus field of the inbox entry (2 for success or 3 for error).

ProcessPersonAttributeChange

This method evaluates all joined accounts belonging to a Person record with attribute changes and produces outbox entries to fulfill the Attibute Flow Rules set for each account store where the person has an account.

 

  • This method is called during Attribute Flow Inbox processing if the SetPersonAttribute() method returns true.

  • Called during Attribute Flow Inbox processing.

  • This method is also called whenever changes occur to a Person record through workflows or APIs.

Usually, only two of the above methods need to be overwritten for translation, one to handle translating the value to a format that can be applied to the Person record in EmpowerID and the other to handle translating the value from the Person record to a native form applicable to the identity entry. The method to overwrite on the inbound side can be either the GetValueForPerson() method or the SetPersonAttribute() method, depending on how you want the inbox entries to reflect the value. GetValueForPerson() is called before the inbox entry is created, and its output is recorded in the inbox entry, while SetPersonAttribute() is called after the inbox entry is created and applied directly to the Person record.

On the outbound side, you override the GetValueForAccount() method. This method translates the value of the outbox entry to the desired attribute for the identity entry.

In this article, we demonstrate how to create a custom Attribute Flow Handler that transforms the State attribute value set on EmpowerID Person from an external account store to the abbreviated value for that state. We demonstrate this by doing the following:

  • Creating an Attribute Flow Handler class library in Workflow Studio and adding code to the class library to:

    • Inherit from the DefaultAttributeflowHandler class

    • Override the GetValueForPerson() method of the DefaultAttributeflowHandler class to abbreviate the State attribute for user accounts in the external system so that those attributes appear in the abbreviated form for each corresponding Person record in EmpowerID with an account in the external system

    • Edit the State Security Boundary Attribute for EmpowerID and the external system in the EmpowerID Web interface

Step 1 – Create the Custom Attribute Flow Handler

  1. In Workflow Studio, right-click on the folder in which you want to create the attribute flow handler and select New Extension or Library > Class Library (.NET Framework).


    This opens the C# Editor for the class library.

     

  2. Click the Save button above the C# Editor and name the file appropriately.

     

  3. Close the class library project and then locate it in your source control tree.

  4. Double-click the project to open it in Visual Studio.

  5. In Visual Studio, open the class library in the editor and add code to do the following:

    1. Inherit from TheDotNetFactory.People.Components.InboxManagers.DefaultAttributeflowHandler base class

    2. Override the GetValueForPerson() method.

      The code should look similar to the following example. Please note that the name of your class will differ accordingly.

      When you create a class library, Workflow Studio automatically adds C=TheDotNetFactory.People.Components as a shorthand Using statement for TheDotNetFactory.People.Components namespace. This allows you to quickly reference the assembly in your code as "C."

       

      public class MyCustomAttributeFlowHandler: C.InboxManagers.DefaultAttributeflowHandler { public override bool GetValueForPerson(AccountStoreIdentityEntry accountStoreIdentityEntry, Person person, AccountStoreObjectAttributeSyncView objectAttributeSync) { } }

       

  6. Add code to the GetValueForPeson() method do the following:

    1. Create a variable to hold the State attributes of a person, calling the getPersonValue() method of the base class to fetch the attributes.

    2. Loop through the State attributes for each account, translating the values for each to the abbreviated form for that state.

    3. Return the translated values.

      The code for the above should look similar to the following.

      public class MyCustomAttributeFlowHandler : C.InboxManagers.DefaultAttributeflowHandler { public override string GetValueForPerson(AccountStoreIdentityEntry accountStoreIdentityEntry, Person person, AccountStoreObjectAttributeSyncView objectAttributeSync) { //Create variable to hold state attributes var state = base.getPersonValue(person, objectAttributeSync).GetAttributeValue("State").ToString(); //Loop through the State attributes and transform each to new value switch (state) { case "Massachusetts": state = "MA"; break; case "Missouri": state = "MO"; break; case "New York": state = "NY"; break; case "Texas": state = "TX"; break; default: state = null; break; } //Return the transformed value return state; } }

       

  7. Next, build the solution to create .pub file for it on your machine. You should see Workflow Studio successfully publish the file.


At this point, the class library is simply published to your local file system. In order to make it available to users in the EmpowerID Web application, you need to run the PublishWorkflowStudioItem workflow in the Web application.

Step 2 – Publish the class library to your environment

  1. Log in to the EmpowerID web application as a user with the appropriate access to run the PublishWorkflowStudioItem workflow.

  2. On the navbar, expand Object Administration > Workflows and click the Publish Workflow Studio Item action link.

     

  3. Click Choose File, navigate to the _PublishedItems folder, select the pub file for the class library you just published, and then click Submit.

Now that the custom Attribute Flow Handler has been created and published, the next step is to instruct EmpowerID to use it for processing the State attributes found in the external account store. This is demonstrated below.

Step 3 – Edit the State Security Boundary Attribute

  1. On the navbar of the EmpowerID Web interface, expand Admin > Applications and Directories and click Manage Schema.

  2. On the Schema page, select the Security Boundary Attributes tab and then click the drop-down arrow to the right of the Search button. This allows you to perform advanced searching.

     

  3. In the Advanced Search dialog that opens, enter State in the Name field and select EmpowerID from the Security Boundary Type drop-down.

     

  4. Click Search to load the grid with the attribute.

  5. From the grid, click the Edit button to the left of the State attribute.

     

  6. In the Edit dialog that appears, do the following:

    1. In the Custom Flow Handler field, enter the full name of the class library you created. This should be similar to TheDotNetFactory.Framework.ClassLibrary.CustomAttributeFlowHandler where CustomAttributeFlowHandler is the name of your class library.

    2. In the Attribute Flow Assembly field, enter the name of the Attribute Flow assembly you just created above, followed by the version number, Culture, and PublicKeyToken information as comma-separated values. This entry should look similar to CustomAttributeFlowHandler, Version=4.0.180.1, Culture=neutral, PublicKeyToken=2d2253f74d4496ef where CustomAttributeFlowHandler and Version=4.0.180.1 is the respective name and version number of the assembly in your environment.

    3. Click Save.

       

  7. Repeat the above steps for the external account store with the attribute you are transforming.

Testing the custom attribute handler

To test the custom attribute handler, create a new test user account in the target account store with an EmpowerID Person linked to that account and set the value of the State attribute to one that is to be transformed, such as Massachusetts. If the handler is working correctly, during the next inventory run, the value of the attribute should be transformed to the appropriate value on the EmpowerID Person.

IN THIS ARTICLE