PeopleSync V6 - Akumina Community

PeopleSync V6

Introduction

The Akumina PeopleSync V6 application synchronizes user properties for the following functionalities:

  • Personalization and targeting (Persona) 
  • Akumina Workspaces 
  • Leveraging AD Groups in SharePoint Security Groups to provide permissions in AppManager 
  • Activity Stream  
  • Social Features such as Comments, Reactions, and Notifications 
  • Company Directory

 The following data sources are supported out of the box but can be configured to synchronize any data source with code development and configuration: 

  • Microsoft Entra ID
  • Any custom sources such as OKTA (Configuration required)

Note:  you can configure to synchronize more than one data source and merge the properties into a single store. The present version of PeopleSync Azure function supports only cloud environment (multi-tenant). 

Dataflow Diagram 

Highlights in V6 Azure Function/Cloud

As part of PeopleSync Azure Function V6, migrated an application from Console to Azure Function to support only Cloud environment. Along with this below are highlighted changes.  

  • Upgraded to .NET 8.0 framework along with Isolated process model.
  • Added feature to logging traces on application insight from custom filter. As dependency for this feature, custom filter dll should have referenced Microsoft.Extensions.Logging.Abstractions package with version of 8.0.0.
  • As part of PeopleSync Azure function, we have a provision to separate or isolate data process for tenant by configuring separate queue and provisioning individual Azure function.
  • Added feature to group Azure search service indexer for tenants, instead of using same service indexer for all tenants. This will allow us to use Azure search service quota maximum and improves search performance.
  • When we move into PeopleSync Azure function, while provisioning new AppManager site from Akumina Portal, admin must review and configure PeopleSync queue, tenant configuration from Akumina portal. If any customer wants an individual queue to process PeopleSync Data, then Azure function provision should be done pointing to new queue configured (this should be done before confirming tenant configuration from Akumina Portal).
  • Akumina Portal now presents Azure Search service sync status, Tenant schema details, configured persona and data processed against each persona.
  • As part of PeopleSync Azure Function, Tenant configuration will be stored on Azure Storage Table instead of config.json.

Required Azure Active Directory “Microsoft Graph” Application Permissions

In order to synchronize data from Azure Active Directory, certain “Microsoft Graph” permissions are required. Visit Graph API Connection for Azure AD, to learn more about the required graph permissions for People Sync and to configure permissions on the associated Graph App.

Configuring PeopleSync  

NOTE: If you have Multiple AppManagers and they are all interfacing to the same O365 tenant, then you need only one PeopleSync to run. AppManagers will use the same PeopleSync EntityPrefixAzureSearchServiceName and AzureSearchServiceApiKey keys. If your AppManager’s websites are interfaced to different Azure Tenants, then you will need to generate an Azure “Search Service” for each AppManager pointing to a different Tenant.  Optionally you may use different prefix to leverage the same cognitive search investment. 

Tenant Configuration

Tenant configuration is a set of required properties used to synchronize the source data from Microsoft Entra ID. Each tenant configuration will be stored on Azure Storage table separately. In the table below an example of adding FetchProperties is given.

Property Type Default Description
TenantId String Domain used to login to your account.

For Microsoft Entra ID – TenantID or DirectoryID (Site Creator we call this the Subscription ID)

ApplicationId String Acquired from the Graph App created to support Akumina. This is the “Application (client) ID” associated with the Graph App.  This is value used in App Manager site creator as the “Application (client) ID”.
ApplicationSecret String Acquired from the Graph App created to support Akumina.  This is the supporting App Graph’s  “Client Secret” VALUE.  Also used in AppManager > Site Creator, the value for “AAD Client Secret”

For Okta, refer to “Configuring Okta application secret” section.

PersonaFieldFilesData  Array of strings [{AppManagerDomain}-tenantid-personaqueryfields.json”]
AkuminaUrlsData JSON AppManager URL
AppManagerQueryKey string Acquired from the AppManager > Site Creator > DigitalWorkplace Core Site > Interchange Query Key
FetchPropertyData JSON In a Multitenant environment this is a custom FetchProperties section that can be defined for each tenant and added to this tenant property area.  Please Refer to the FetchProperties section section below to add additional custom FetchProperties for this tenant.
FetchOptionsData JSON In a Multitenant environment this is a custom FetchOptions section that can be defined for each tenant and added to this tenant property area. Please Refer to the FetchOptions section below for additional information.
FieldsMappingSource String “fieldsmapping.xyz.json“ Name of the json file that contains the JSON formatted mapping of field names (graph property name to front end property name) and default language. In a multi-Tenant environment this file name should be unique to the client/tenant example fieldsmapping.xyz.json, since this would need to be a unique name for this tenant area.
CustomFilterAssembly String “” In a multi-Tenant environment, this CustomFilterAssembly will be set if a Custom filter is required for this specific tenant.  Please see the following link for additional information: AkuminaSamples/PeopleSync/Net8 at master · akumina/AkuminaSamples · GitHub
Environment String Environment Name
FrontEndStorageConnection String Azure Storage Account used for Headless front end. If Headless frontend is not used, then this configuration is not required to synchronize the User Profile. From Azure Portal – This is the Storage Account > Access Keys > ConnectionString.

FetchOptions

Global fetch options are used if Tenant specific fetch options are not configured. Include all FetchOptions at Tenant Specific, if you need to override any one of the fetch options then set at Global FetchOptions.

SyncUsers Boolean true Synchronize configured user properties
SyncGroups Boolean true Synchronize Active Directory Groups
SyncUsersAssignedToNoGroups Boolean true Set to true, all users will be synced.  If the value is false, then users who are not assigned to any groups will be filtered out of the people sync.
SyncTags Boolean false Set to true if Akumina Workspace Licensed and configured
SyncTypes Boolean false Set to true  if Akumina Workspace License and configured
TrackUserGroupChange Boolean true Enumerates the user changes for ActivityStream Access Control update.
TrackUserPersonaChanges Boolean true Enumerates the user changes for ActivityStream Access Control update.
MergeGroupFieldsToUserGroup Boolean true Duplicates the GroupFields into UserGroups entity.

 

FetchProperties 

Global FetchProperties are used if Tenant specific FetchPropertiese are not configured. 

Property Type  Default   Description 
TagExtension  String  groupname  Tenant based TagExtension value. If we need to overwrite the default TagExtension, then we can include the values here otherwise we can keep this as empty or remove the property. 
TypeExtension  String  groupuser  Tenant based TypeExtension value. If we need to overwrite the default TypeExtension, then we can include the values here otherwise we can keep this as empty or remove the property. 
ExpandProperties  String  “”  If the value returned as JSON then the system will generate linear string property of the value.  For example if the field defined returns the JSON of “P” as {“P1”:”V1”,”P2”:”V2”} then the property expanded as P_P1 with value V1 and P_P2 with value P2 
UserProperties  String  “id,accountEnabled,businessPhones,
city,companyName,country,
deletionTimestamp,department,
onPremisesSyncEnabled,displayName,
facsimileTelephoneNumber,givenName,
jobTitle,mail,mailNickName,mobilePhone,
objectType,officelocation,
physicalDeliveryOfficeName,
postalCode,preferredLanguage,
sipProxyAddress,state,
streetAddress,surname,
telephoneNumber,usageLocation,
userPrincipalName,userType,otherMails,
provisionedPlans,provisioningErrors,
proxyAddresses,schools,skills,birthday,hiredate” 
You can add remove any properties defined in your Identity provider or data source.

Please refer Required Fields section for optimal functionality require fields in Akumina software. 

UserExtendedProperties  String  Manager,AssignedLicenses,
AppRoleAssignments,DirectReports,
OwnedDevices,RegisteredDevices,
OtherProperties,UserPreferences” 
Extended properties are complex object needs multiple calls to data source.  You can add or remove any supported properties 
GroupProperties  String  id,description,displayName  Group properties 
PersonaUserProperties  String  mail,displayName,userPrincipalName,
businessphones,aklanguageid” 
Persona properties 
UserGroupUserProperties  String  displayName,userPrincipalName,
businessphones,aklanguageid 
User Group properties 
SkipUsers  String  “”  Specify condition like “display=xyz,location=boston”  it will then skip users whose value starts with defined conditions.  Example: 

“SkipUsers”: “givenName=Firstname,givenName=Test,givenName=GiveName,department=Dummy”,

In the above users whose givenName, starts  with Firstname or Test or GiveName or are in department beginning with Dummy will be excluded.

SkipGroups  String  “”  Specify condition like “display=group1” it will then skip Groups whose value starts with defined conditions. 
LargeContentProperties  String  DirectReports   
ConvertValueToLowerCase  string  “userPrincipalName,mail,userEmail  We will convert these user properties to all lower case.
BooleanProperties  String  “accountEnabled  This property should be set at Global fetch properties.
DateTimeOffsetProperties  String  “CreationDate  This property should be set at Global fetch properties.
SavePeoplePictureAs String  “userPrincipalName  Based on this comma separated AAD property name, the User’s profile picture will stored in the blob (when ProfilePictureStorageAssemblyType & FrontEndStorageConnection configurations are set). For. eg., if we need to clone the image with mail value of the user, then the value will be set it as “userPrincipalName,mail”.

FetchProperties UserExtendedProperties field expansions 

Some properties are extendable, the following table summarizes the columns included in the UserExtendedProperties. 

UserExtendedProperties  Fields retrieved 
Manager  Manager 
AssignedLicenses  All Licenses and Count 
AppRoleAssignments  id, principalDisplayNameprincipalIdprincipalTyperesourceDisplayNameresourceId 
DirectReports  displayNamegivenName, surname, mobilePhonebusinessPhonesjobTitle, mail, officelocationpreferredLanguageuserPrincipalName 
OwnedDevices  deviceIddeviceMetadatadeviceVersionoperatingSystemoperatingSystemVersiontrustTypedisplayName 
RegisteredDevices  deviceIddeviceMetadatadeviceVersionoperatingSystemoperatingSystemVersiontrustTypedisplayName 
OtherProperties  All the other external properties configured in the AAD 

 

Required Fields 

Customers can add or remove fields in the PeopleSync importer to customize their people data import, enabling features like persona-driven experiences. Akumina software requires the following fields for optimal functionality.

Core Field Mapping Field Feature Required
Id / objectId id Core
userprincipalName userPrincipalName Core
mail mail Core
givenname givenName Core
surname surname Core
displayName displayName Core
accountEnabled accountEnabled Core – Used within PeopleSync filter to remove disabled accounts.
IsExternalUser Core – Calculated field from userPrincipalName; if #ext is presented the user marked as external.
aklanguageid languageid Unless configured this can use constant (ex., 1033)
office officelocation Employee Details – FS3, FS4
department department Employee Details – FS3, FS4
People Directory – FS3, FS4
cellphone mobilePhone Employee Details – FS4
mail mail Employee Details – FS3, FS4
People Directory – FS3, FS4
displaybirthday birthday Employee Details – FS3, FS4
techskills skills Employee Details – FS4
mobile mobilePhone Employee Details – FS4
jobtitle jobTitle Employee Details – FS3
People Directory – FS3, FS4
mobilephone mobilePhone Employee Details – FS3
People Directory – FS3
skills skills Employee Details – FS3
businesphones businessPhones People Directory – FS3, FS4
usageLocation usageLocation People Directory – FS3, FS4
manager_displayname Manager (ExtendedUserProperty) People Directory – FS4
pictureurl Additional Configuration with Front End Storage Connection People Directory – FS3
officelocation officelocation People Directory – FS3
facsimiletelephonenumber facsimileTelephoneNumber People Directory – FS3

Custom Filter Assembly

When you want to implement custom logic to filter Group and User data. You can refer to the link below for template and implement your own filter logic.

AkuminaSamples/PeopleSync/Net8 at master · akumina/AkuminaSamples · GitHub

Even customer has multiple sites for the same tenant, only single custom filter assembly is supported. You can reach a support team for custom filter deployment and configuration.

FieldMappings

In Azure function default field mapping is configured in the below format.

 

Prefix: Set unique value to this field if you need to initialize prefix to fields, this is required to uniquify the fields if you sync cross multiple data sources. 

PrefixExclude: System defined; you can add but cannot remove the default values 

Group: For any customization of the Group fields.  Example in your AD you may have a group column called “id” (read in column) but in the Akumina framework you want id to really be objectId (write out to), then the field mapping will become “Id”:”objectId”

Users: For any customization of the User fields, for example in your AD you may have a field called _firstname (reads in) but in the Akumina framework you want to have it represented as FirstName (write out to), then the field mapping will become “_firstname”:”FirstName”  

UserGroups:  Same as “Users” but the property related to user groups 

UserPreferences: Same as “Users” but the property related to user preferences 

Note: Any value that starts with “~” is a constant. For example:  “~1033″:“aklanguageid” : will be stored in our system column aklanguageid=”1033” for the site default language. 

Creating a custom fieldmapping file for a tenant

A custom fieldmapping file can be created to change things such as default languages or mappings.  Example fieldmapping.french.json or fieldmapping.*.json, where * is the unique name used for this tenant’s ( * could be clientname) fieldmapping json file.  In the example below, start with the appropriate fieldmapping type file associated with your source data e.g. aad, okta or sharepoint. In the case where aad is the source,  copy fieldsmapping.aad.json and rename the file to be unique for your tenant in this example fieldmapping.French.json.  This tenant should have default language set to French.  Edit the file and change the language code from ~1033 to ~1036. example:

In the “Tenant Configuration” area of the config.json, set the FieldsMappingSource to this newly created file in the people sync directory example:

Configuring Okta application secret

This is for sample purposes only to show you how to configure Okta:

  • Login as an Administrator for Okta Account using domain name.
  • From Application home page, use “Admin” button to navigate to Admin Dashboard page
  • Navigate “API” link in “Security” menu to land into “Token” page
  • Click on “Create Token” button to initiate the token generation screen
  • Enter any token name in the field and click “Create Token” button to generate token.
  • New token will be generated and displayed in the screen. Copy this token for future reference.
  • This token will expire in 30 days if it’s not used. Expiration will extend for next 30 days whenever we use it. Please make sure to configure the valid Token to run the sync.

Here’s an example of Okta fields mapping:

 

Setting up PeopleSync Azure Function on Cloud

Follow below steps to provision new Azure Function App to setup PeopleSync process along with configuration to be done on Akumina portal.

    • Create a new Function App from Azure portal.
  • While creating a new function App, make sure that below mentioned configurations selected with highlighted values. Refer to the screenshots below for more clarity and information to be fed on each tab. Once you reach the final tab Review + Create, then review all the properties and click on create button.
          • Runtime stack => .NET
          • Version => 8 (LTS) Isolated (Early Access)
          • Hosting => Functions Premium

    • Once a Function App is created for PeopleSync, then deploy latest version of PeopleSync Azure Function code.
    • Below configuration value should be added and saved on Function App Configuration tab. Leave default properties set while creating Azure Function App.

 

[

{

“name”: “AzureConnectionString”,

“value”: “”,

“slotSetting”: false

},

{

“name”: “DefaultFetchProperties”,

“value”: “{ \”TagExtension\”: \”\”, \”TypeExtension\”: \”\”, \”ExpandProperties\”: \”\”, \”UserProperties\”: \”id,accountEnabled,businessPhones,city,companyName,country,deletionTimestamp,department,onPremisesSyncEnabled,displayName,facsimileTelephoneNumber,givenName,jobTitle,mail,mailNickName,mobilePhone,objectType,officelocation,physicalDeliveryOfficeName,postalCode,preferredLanguage,sipProxyAddress,state,streetAddress,surname,telephoneNumber,usageLocation,userPrincipalName,userType,otherMails,provisionedPlans,provisioningErrors,proxyAddresses,schools,skills,birthday\”, \”UserExtendedProperties\”: \”Manager,AssignedLicenses,AppRoleAssignments,DirectReports,OwnedDevices,RegisteredDevices,OtherProperties,UserPreferences\”, \”GroupProperties\”: \”id,description,displayName\”, \”PersonaUserProperties\”: \”mail,displayName,userPrincipalName,businessphones,aklanguageid\”, \”UserGroupUserProperties\”: \”displayName,userPrincipalName,businessphones,aklanguageid\”, \”SkipUsers\”: \”\”, \”SkipGroups\”: \”\”, \”LargeContentProperties\”: \”DirectReports\”, \”DateTimeOffsetProperties\”: \”CreationDate\”, \”ConvertValueToLowerCase\”: \”userPrincipalName,mail,userEmail\” }”,

“slotSetting”: false

},

{

“name”: “EmailSettings”,

“value”: “”,

“slotSetting”: false

},

{

“name”: “MaxSearchIndexCount”,

“value”: “4”,

“slotSetting”: false

},

{

“name”: “PeopleSyncQueueName”,

“value”: “peoplesync”,

“slotSetting”: false

},

{

“name”: “PeopleSyncTaskPoisonQueueName”,

“value”: “peoplesynctask-poison”,

“slotSetting”: false

},

{

“name”: “PeopleSyncTaskQueueName”,

“value”: “peoplesynctask”,

“slotSetting”: false

},

{

“name”: “PortalConnectionString”,

“value”: “”,

“slotSetting”: false

},

{

“name”: “ProcessCount”,

“value”: “5000”,

“slotSetting”: false

},

{

“name”: “SupportPeopleSync”,

“value”: “true”,

“slotSetting”: false

},

{

“name”: “WEBSITE_MAX_DYNAMIC_APPLICATION_SCALE_OUT”,

“value”: “5”,

“slotSetting”: false

}

]

  • Make sure to review following configurations and update with proper value on PeopleSync Azure Function.
    • PeopleSyncQueueName
    • PeopleSyncTaskPoisonQueueName
    • PeopleSyncTaskQueueName
  • Make sure to review whether “PeopleSyncQueue”, “PeopleSyncTaskPoisonQueue”, “PeopleSyncTaskQueue” are created on respective storage.
  • Go to the Function App Identity tab. In that go to section System assigned and select status as “ON”. Then save this change, will create object principal id. You must add this principal id on portal and AppManager key vault access policy with access of Get, List for both Key permissions and Secret permissions.


  • Once you complete the above steps, the creating Azure Function App for PeopleSync process is complete. After this while provisioning site from Akumina portal below steps to be taken care to complete PeopleSync process setup for a particular tenant.
  • Once you initiate new site provision from Akumina portal. Provisioning on Azure portal will be completed. Then comes to tenant configuration to complete PeopleSync process.

Click on below highlighted Add button on subscription screen to provision new site.

After clicking Add button, Popup window comes up to initiate site provision.

After provisioning for new site completed, click status icon from subscription screen to proceed further on tenant configuration.

  • Once tenant configuration is generated, you will be receiving mail to login into Akumina portal to review and confirm. Review Fetch Properties, Fetch Options and PeopleSync Queue (This queue name is PeopleSync Task Queue) and then click on Review & Confirm button.

  • Once Tenant schema properties are created based on fetch properties, you will be receiving mail to review and confirm, and this step completes Azure Function App PeopleSync process setup.

Views: 167
//]]>