User and Group Sync Guide

User and Group Sync Guide

Overview

This document is intended to explain how the ONE User and Group Sync feature works to enable ONE customers to synchronize the users and groups into the ONE Platform with their internal systems. The ONE User and Group Sync feature also supports the ability to execute automated user deletion.

User Synchronization

The ONE Platform supports many user management features. Sometimes organizations would like to automate user synchronization with a back end user store. In these cases, the ONE User and Group Sync feature allows organizations to keep the ONE user store synchronized with their user store by importing and removing users from the ONE platform.

User Import

The ONE User and Group Sync feature also allows the user to be imported by using a userstosync.csv file. When this feature is used, full user accounts are created with the capability of setting the following user properties:

• First Name
• Last Name
• UPN (usually email)
• Role
• Language
• Password (user must change upon first login, and this is optional)
• Sendemail (if a user should receive a welcome email with a temporary password, if not specified in the password field, a unique password will be generated)
• Alternate/Contact Email
• Contact Phone Number

User Deletion

In some ONE configurations, user de-provisioning happens at the authentication provider level and not at the ONE console level. This causes user records to persist in the ONE platform which is usually an issue for business stakeholders looking at user metrics. ONE provides an endpoint in the GroupSync feature that allows organizations to remove users from the ONE platform.

ONE Groups Synchronization

The ONE platform allows productivity content to be routed to users based on a group subscription model. A ONE user can be a member of single or multiple groups. When a ONE Productivity Card is sent to a specified group, all users within this group will see the published card content in their ONE Productivity Stream (HUB). A good example of the use of this feature is the ONE Cloud Communications module. The Cloud Communications module allows Corporate Communications messages to be published and sent to specific users by the use of the ONE Groups feature. In addition to the Cloud Communications module, any system that publishes productivity cards to the ONE platform can leverage group targeting.

Most organizations today already group their employees in some way to streamline many business functions. These groupings take on many forms such as email groups, security groups, regional groups etc. The ONE platform is designed to be synchronized with these organizational groups using a feature called ONE Group Synchronization.

Auto User Creation

ONE also provides the capability to automatically add stub a user's records to the ONE platform during the GroupSync process. This is helpful when wanting users to have a targeted group in their feed when they log in for the first time. If the user record isn’t created during group sync, new users will need to wait until the next GroupSync process to execute before they will only see the targeted content after the next GroupSync process occurs. It is important to note that this function does not create full user accounts that users are able to use to log in. For full user account creation, see the User Import section below. To employ this feature, please reach out to a customer success manager to enable this capability in a tenant.

ONE Group Synchronization Methods

The ONE User and Group Sync feature currently supports 3 different methods for organizations to synchronize their groups with the platform.

1. User Initiated CSV upload
2. CSV Upload Web Service
3. CSV On Premise Windows Service Synchronization

 

User Initiated CSV Upload (Method 1)

This synchronization method allows a ONE user with Cloud Communications or tenant administration rights to manually upload a predefined group and member files to the platform. The file format for these files is the Comma Separated Values (CSV) format.

Usage

To Import users using the ONE Cloud Communications Console, a user first needs to log in to the system with either tenant administration or Cloud Communications administration rights. The user then needs to navigate to Cloud Comm > Users and Groups > Import

On the Import Groups and Members Dialog, administrators can choose a file on their local computer for upload.

The format of the CSV can be referenced in the Appendix A: CSV File Structure

 

 

CSV Upload Web Service (Method 2)

The web service CSV upload method allows organizations to automate the sending of the groups.csv and groupmembers.csv files to ONE through a REST-based web service hosted in the ONE platform. This service also supports user file deletion, named usertodelete.csv to handle use de-provisioning.

Usage

Service Address

https://one.sitrion.com/api/v2/groupsync/csv 

HTTP Method

POST

HTTP Authorization Headers

1. Header: Authorization
   1. Bearer: sitauth
   2. Value: base64 encoded company password
      1. This value can be retrieved from the tenant administration Get Started Page
2. Header: sitrion-companyId
   1. Value: ONE tenant company ID
      1. This value can be retrieved from the tenant administration Get Started Page

Data Contract

The payload for this post request is that the files be included in a multipart form-data payload. All files can be sent at once, or just by one at a time.  Below are the header and payload details for the multipart form-data structure. See Appendix B: Example Web Service Code. For informationation on how to format the CSV files for this method, please refer to Appendix A: CSV File Structures.

Multipart Form-Data Header

1. Header: Content-Type
   1. Value: multipart/form-data; boundary=---------------------------7e02261d507e4
      1. Where the boundary value can be anything but should be a value that will not appear in any part of the file being transmitted.

 

Post Multipart Form-Data Payload

Below  is an example of a multipart/form-data payload that includes two files (groups.csv and groupmembers.csv)

 

-----------------------------7e02261d507e4

Content-Disposition: form-data; name=groups.csv; filename=groups.csv

U,groupId,GroupFriendlyName

U,groupId2,GroupFriendlyName2

-----------------------------7e02261d507e4

Content-Disposition: form-data; name=groupmembers.csv; filename=groupmembers.csv

groupId,e12345

groupId2,e12345

groupId,e22345

groupId2,e22345

-----------------------------7e02261d507e4--

 

CSV on Premise Windows Service Synchronization (Method 3)

The ONE Collector service allows organizations to automate the process by installing on an on-premise windows service that watches a folder for new files, and when new files are added, will perform synchronization with the ONE platform. This method also has a unique capability of also sending welcome cards to all newly imported users.

Prerequisites

1. A Windows server/workstation
2. The server/workstation requires outgoing HTTP ports 80 and 443
3. Get Group Sync Task Assembly from ONE

Installation Instructions

1. Get the ONE Collector service from the tenant administration Get Started page
   
   • Or downloaded directly from here
2. Install the downloaded MSI on the system
3. Stop the ONE Collector service in the Windows Services Console
4. Restart the ONE Collector service in the Windows Services Console

Usage

To trigger a sync, add one or many of the CSV file(s) into the ImportFiles folder created in the installation steps. Please refer to Appendix A: CSV File Structures on how to format the CSV files for this method.

After every synchronization, the service will archive all files by renaming them to unique names. When importing users or deleting users, the service will process the import files in groups of 100 records. Each group will be removed from the import file and added to a unique processed file {originalFilename}{guid}.csv

 

Custom Import Folder

To set the service to use a different folder location for file imports, a configuration file needs to be created.

1. Create a file named CsvGroupSyncSettings.json in the Tasks folder where the windows service is installed.
2. Add the following content to the FilesPath where the path value is the path that the service should import files from.
   1. {  "FilesPath": "C:\\Program Files\\Sitrion\\Sitrion ONE Collector Service\\Tasks\\ImportFilesFromConfig" }

 

Importing Errors

If the collector service encounters an importing error, it will rename the group files to {originalFilename}{guid}-error.csv

Send Welcome Card

The Windows Collector service enables a unique capability that can send a welcome card(s) for each user imported via the userstosync.csv file.

Configuration Instructions

1. Create a folder named Cards under the ImportFiles folder
2. A card will be sent to each user in the user import (userstosync.csv) for each instance of a *.json file found in the Cards folder
3. See Appendix C: Sample Card JSON file for an example *.json file
4. It is highly recommended that you consult with your customer success manager if undertaking this task.

 

Appendix A: CSV File Structures

The ONE User and Group Synchronization feature allows for three different CSV file structures to be uploaded to the system. 

Userstosync.csv

This file is used to add full user accounts to the ONE platform. This should only be used if using the Limeade ONE authentication provider. If using a different authentication provider, this file should not be used.

The userstosync.csv file structure is the following:

Firstname,lastname,email,role,language,password,sendemail,AltEmail,Phone

Note that the column headers are optional.

Column	Description
Firstname	Users First Name (Required)
Lastname	Users Last Name (Required)
Email	Users Email address or Unique ID (UPN) (Required) – This will be the user’s login credential
Role	Which role should the user be placed in. The value here should match the role name defined in the Roles section of the tenant administration console. If no value is specified, the user will be placed in the default role which is set on the User Settings section in the tenant administration console.
Language	Users primary language. If no value is specified, the user will be set to the tenant default language.
Password	Users initial, temporary password. This field is not required. If sendemail is TRUE, user will be provided the set password in the welcome email
Sendemail	Accepts one of two values (TRUE or FALSE) TRUE is default if no value is provided. If set to TRUE the user will receive a welcome email. This email will include the user’s initial temporary password. It is highly recommended to avoid setting this value to FALSE if the password column does not contain a value. In this case, the user will be unable to login without doing a password reset action.
AltEmail	Users alternate or contact email. When filled out this email will be used to communicate with the user from the platform
Phones	Users contact phone number. Will only be used/displayed in the user profile if profiles are deployed.

 

Example Row Entry

Kelly,Gault,kelly.gault@limeade.com,default,en,@StrongPassword!,TRUE,kellygault@domain.com,555-555-5555

This entry will add a new full user to the ONE platform's authentication provider named Kelly Gault with a login of kelly.gault@limeade.com into the role named default. It would also set the user language to English and an initial password of @StrongPassword!. The TRUE parameter ensures that a welcome email is sent to kelly.gault@limeade.com

Userstodelete.csv

This file indicates the platform that users should be removed from within the ONE platform.

The userstodelete.csv file structure is the following:

user ID

Please note that no columns should be added

Column	Description
User ID	User ID – Typically Email or UPN (Required)     This user ID must be the user ID that is stored in the ONE platform. This is usually a user's email, but may also be the unique user ID provided by the custom authentication provider should ONE's out of box authentication provide is not being used.

 

Example Row Entry

Kelly.gault@limeade.com

This entry would mark the user with user ID kelly.gault@limeade.com as deleted in the ONE user store. The user would not be removed from the system and would need to be removed from the deleted users list.

Groups.csv

Note that all groups do not need to be synchronized to add or delete a new group. The groups.csv file is incremental and a partial update/addition list can be sent, or a list can just be deleted, though Limeade recommends to always synchronize the entire system to avoid confusion.

The groups.csv file structure is the following:

Operation Flag, External Group ID, Group Name

Please note that no columns should be added.

Column	Description
Operation Flag	This column supports two possible flag values. U for Update, and D for delete. The Update (U) flag indicates that the synchronization system to update the name of the group in the ONE Group store. This flag should be the default flag used for all uploads unless it is desired to delete the group. The Delete (D) flag indicates that the synchronization system should remove this group from the ONE Group store.
External Group ID	This column is an organizations unique identifier for the group. The ONE group feature stores its own unique group ID and this column allows ONE to match a specific group based on an organization's unique group ID. Note that this ID should be a string of any length and contain no quotes, commas or special characters
Group Name	This column is the group name to be displayed to the user in the Cloud Communications Module. These names should be friendly for communication writers to allow for intuitive access. This column is a string that can be no more than 256 characters long and should not contain commas. Limeade recommends much shorter names for ease of lookup.

Example Entry

U,AD23F45C234A323,My Group Name

This entry would trigger an update to the group identified by the external ID AD23F45C234A323 and make the group name My Group Name.

Groupmembers.csv

It must be noted that it is required to synchronize the entire user population with the groupmembers.csv file. The group membership will always be reset when this file is uploaded, and therefore, to remove a user from a group, the entire set of users needs to be synchronized.

Multiple groupmembers.csv files can be synchronized if a single file that contains all desired groups and members cannot be extracted. If loading multiple files, stagger the posting of each file. The Limeade system cannot process multiple files at the same time that have the same file name. 

The groupmembers.csv file structure is the following:

External Group ID, user ID

Please note that no column headers should be added.

Column	Description
External Group ID	This column is an organization's unique identifier for the group the user specified in the next column is to be a member of. This ID requires that it match with an existing group that has been provided by the groups.csv upload.
User ID	This column is the unique identifier for the user desired to be included in the group specified by the external group ID, specified in the previous column. This user ID must be the user id that is stored in the ONE platform.  This is usually a user’s email but may also be the unique user ID provided by a custom authentication provider, if ONE’s out of box authentication provider is not used.

 

Example Entry

AD23F45C234A323,myUserID@limeade.com

This entry would trigger an addition of the user myUserID@limeade.com to the group identified by the external ID A23F45C234A323.

Appendix B: Example Web Service Code

Adding Web Request Headers

public static void AuthorizeWebClient(WebClient webClient, string companyPassword, Guid companyId)

{

webClient.Encoding = Encoding.UTF8;

webClient.Headers[HttpRequestHeader.Authorization] = 

"sitauth " + Convert.ToBase64String(Encoding.Default.GetBytes(companyPassword));

webClient.Headers["sitrion-companyId"] = companyId.ToString("D", CultureInfo.InvariantCulture);

webClient.Headers.Add(HttpRequestHeader.ContentType, "application/json; charset=utf-8");

}

Calling Web Service

public void Run()

{

try

{

var path = Path.Combine(Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location), "ImportFiles");

 

//Looking for import files at : {path} 

 

if (!Directory.Exists(path))

{

//ImportFiles folder doesn't exist: {path}.

return;

}

 

var groupsFile = new FileInfo(Path.Combine(path,"groups.csv"));

var groupmembersFile = new FileInfo(Path.Combine(path,"groupmembers.csv"));

 

if (!groupsFile.Exists && !groupmembersFile.Exists)

{

//groups.csv and groupmembers.csv not found in ImportFiles folder.

return;

}

 

// Copy files to new name to have them archived.

// Read from the copied file.

if(groupsFile.Exists)

{

var targetName = Path.Combine(groupsFile.DirectoryName,

$"{Path.GetFileNameWithoutExtension(groupsFile.FullName)}{Guid.NewGuid()}.csv");

groupsFile.MoveTo(targetName);

groupsFile = new FileInfo(targetName);

}

if (groupmembersFile.Exists)

{

var targetName = Path.Combine(groupsFile.DirectoryName,

 $"{Path.GetFileNameWithoutExtension(groupmembersFile.FullName)}{Guid.NewGuid()}.csv");

groupmembersFile.MoveTo(targetName);

groupmembersFile = new FileInfo(targetName);

}

 

using (var client = new HttpClient())

using (var formData = new MultipartFormDataContent())

{

if (groupsFile.Exists)

{

var groupsFileStream = new StreamContent(groupsFile.OpenRead());

formData.Add(groupsFileStream, "groups.csv", "groups.csv");

}

 

if (groupmembersFile.Exists)

{

var groupMembersFileStream = new StreamContent(groupmembersFile.OpenRead());

formData.Add(groupMembersFileStream, "groupmembers.csv", "groupmembers.csv");

}

 

 

var url = $"{Configuration.EnvironmentName}/api/v2/groupsync/csv";

var request = OneWebClientHelper.AuthorizeHttpRequest(Configuration.CompanyPassword,

Configuration.CompanyId); 

request.Content = formData;

request.RequestUri = new Uri(url);

request.Method = HttpMethod.Post;

 

var response = client.SendAsync(request, HttpCompletionOption.ResponseContentRead,

 CancellationToken.None).Result;

 

_logger.LogInfo(response.IsSuccessStatusCode ? "Import files successfully sent." : 

"Error occured.");

if (response.Content != null)

{

var result = response.Content.ReadAsStringAsync().Result;

if(!string.IsNullOrWhiteSpace(result))

//Response message : {result}");

}

}

}

catch (Exception ex)

{

//Log your error

}

 

}

Appendix C: Sample Card JSON file

Please note that {newid} will ensure a unique ID is used for sending the card to the user.

{

  "Actor": {

    "DisplayName": "John Actor",

    "Email": "test@email.com"

  },

  "CardId": "welcome1.{newid}",

  "MessageType": "Test.Welcome1",

  "Data": {

"WelcomeMessage" : "Welcome"  

  },

}