User profile synchronization

In this section detailed information on how load user profile information from external sources is provided. Syntphony different endpoints to load user profile information are introduced.

Enable external user profile integration

First step to apply for the organization is to enable user profile integration with external sources. To do so, an Azure administrator needs to browse to product Azure storage account > Tables > Settings

Search for a setting called “SyncConfiguration”

It will have the following JSON format.

SyncConfiguration

{
  "TogoUPEnabled":true,
  "SharePointUPSync":true
}

TogoUPEnabled: Mandatory. Enables user profile synchronization with external data sources.
SharePointUPSync: Optional. Enables user profile synchronization with SharePoint profiles. While activated, the process will also sync profile metadata to SharePoint user profiles. For this synchronization, the properties may previously exist in SharePoint user profile service. Due to technical limitations, the process can not create them automatically.

User profile file format

Syntphony is prepared to ingest user profile data using a specific JSON format file, including all the profile properties used later on audiences purposes.

It basically consists in an Array of JSON user objects with different required information.

The format of the JSON file is the one shown below:

User profile format

 
{
  "users":  
    [
      {
        "userId":  "user identifier",
        "name":  "User name",
        "jobTitle":  "Job Title",
        "upn":  "user@domain.onmicrosoft.com",
        "email":  "user@domain.onmicrosoft.com",
        "account":  "user@domain.onmicrosoft.com",
        "loginName":  "user@domain.onmicrosoft.com",
        "locale":  "es-ES",
        "audienceDepartment":  "Department",
        "department":  "Department",
        "audienceLocation":  "Location",
        "location":  "Location",
        "phone":  "phone number",
        "mobile":  "mobile number",
        "entityType":  "User",
        "extended_props":  
          [
            {
                "Key":  "Property 1",
                "Type":  1,
                "Value":  "Property 1 value"
            }
          ]
      }
    ]
}

Field name	Field description
userId	Unique identifier
name	Name
jobTitle	Job description
upn	User principal name
email	Email
account	Account
loginName	Login name
locale	User profile language. It applies on multilanguage scenarios.
audienceDepartment	Audience department
Department	Department
audienceLocation	Audience location
Location	Location
phone	Phone number
mobile	Mobile phone number
entityType	Type of entity. The value is always: User
extended_props	Extended properties of the user profile. Explained in the following section

User profile extended properties

Extended properties are the additional properties that can be defined and customized in order to create audience conditions. They can be added as a JSON array of properties with the follow structure

Extended properties

 
[
  {
      "Key":  "Property Key",
      "Type":  1,
      "Value":  "Property value"
  }
]

The posible values for Type property are

Type Number	Type description
1	String
2	Boolean
3	Integer
4	Date time
5	Double
6	Guid
7	Option
99	None

User profile synchronization. Endpoints

Syntphony provides different approaches to send user profile information and will be described below.

1. Batch Process

User profile process and synchronization in batch mode. It synchronizes also existing user profiles in SharePoint.

Important In order to sync user profiles with properties in SharePoint, properties as well as user profiles should exist.

Permissions

Permission type	Permissions (from least to most privileged)
Application	User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All

HTTP Request

POST [user_profile_api_url]/app/togouserprofile/batch/upsert

Request headers

Header	Value
Authorization	Bearer [token] (required)
Content-Type	application/json (required)

Request body

{
  "users":  
    [
      {
        "userId":  "user identifier",
        "name":  "User name",
        "jobTitle":  "Job Title",
        "upn":  "user@domain.onmicrosoft.com",
        "email":  "user@domain.onmicrosoft.com",
        "account":  "user@domain.onmicrosoft.com",
        "loginName":  "user@domain.onmicrosoft.com",
        "locale":  "es-ES",
        "audienceDepartment":  "Department",
        "department":  "Department",
        "audienceLocation":  "Location",
        "location":  "Location",
        "phone":  "phone number",
        "mobile":  "mobile number",
        "entityType":  "User",
        "extended_props":  
          [
            {
                "Key":  "Property 1",
                "Type":  1,
                "Value":  "Property 1 value"
            }
          ]
      }
    ]
}

Response

If successful, this method returns a 200 OK response code.

2. Upload user profiles file

It allows synchronization by uploading a file with the JSON format. It synchronizes also existing user profiles in SharePoint.

Permissions

Permission type	Permissions (from least to most privileged)
Application	User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All

HTTP Request

POST [user_profile_api_url]/app/togouserprofile/uploadfile

Request headers

Header	Value
Authorization	Bearer [token] (required)
Content-Type	multipart/form-data (required)

Request body

Append user profile JSON file as form-data

Response

If successful, this method returns a 200 OK response code.

3. SharePoint synchronization check

After executing one of the previous steps to sync user profiles, it is posible for an administrator to see if there are errors in SharePoint synchronization.

To do so, navigate to syntphony site configuration (/sites/togo) > Site Contents > UserProfileSync (folder). Find here in the TogoUPErrorDetail if there is any error in the process or the process has finished correctly.

Applying audiences Communities