How to Use the User Bulk Uploader

About the User Bulk Uploader 



Do you ever find it challenging and time-consuming to manage hundreds or thousands of users and their associated data? With the User Bulk Uploader, a java based application for Verint it reads a CSV data file and uses it to create and/or update user data in Verint. In addition to uploading/updating user profile data the tool allows you to add users to security groups and each user’s manager. 



System Requirements:

  • Java 8 or 11 SE (Standard Edition) Runtime Environment



Key Features: 

  1. Offers easy user management at a larger scale

  2. Allows you to bulk manage user profile data

  3. A java based application 

  4. Ability to bulk upload community members

 

 

 

 

 

Run the User Bulk Uploader

  1. Open Command Line (application) on your PC/ MAC



1.1 The simplest way to run the tool is to execute this command at the command line.

java -jar telligent-userimporter-1.0.x.jar



1.2 The tool will look in the current directory for a file named application.properties, which is the file that contains the configuration for the tool.



1.3 ​​Optionally you can pass one or more of the properties on the command line.  In this example, we are passing the Telligent password on the command line.  The tool will read the properties from the application.properties file first, and then apply any properties passed at the command line as an override.

      java -jar telligent-userimporter-1.0.x.jar --telligent.key="MyKey"

 

Configure the User Bulk Uploader



The following is a list of properties that can be passed to the tool by placing them in the application.properties file, or by passing them as arguments on the command line.

 

Properties

Required or Optional?

Notes/ URLs

telligent.url

Required

The URL to Telligent.  e.g. https://community.telligent.com

telligent.user

Required

The Telligent username of a user with User Admin access

telligent.key

Required

The key from the Telligent username that was provided. You have to generate your key from user selected above on the page https://your_telligent_community/user/myapikeys

infile

Required

The filename of the CSV file that contains the user data to be imported into Telligent.

logging.level.com.socialedge=DEBUG

Optional

This will turn on additional logging that will provide deeper details on actions that are being taken inside of the application.  Generally the only time you would enable this level of logging is if SocialEdge support requests it in order to debug an issue you are having.

logging.level.org.apache.http.wire=DEBUG

Optional

This will turn on detailed logging of the network traffic being sent to and received from Telligent.  This is useful when the above logging option isn’t providing enough detail to troubleshoot an issue.  Note that this level of logging will log Telligent server credentials to the log file.



Example application.properties File



telligent.url=http://127.0.0.1

telligent.key=3yxa2gl4pi

telligent.user=admin

infile=./files/userdata.csv



Formatting the CSV File

The user importer takes as input a CSV file that contains your user data along with column headings that provide the tool with information that it needs to create or update the user profiles.  The following is a checklist of items needed when generating your CSV file, below which is a section that explains each of these items.



  • Create a valid CSV file with your user data in it.

  • When updating existing users ensure that at least one locator type column is present.

  • When creating users ensure that all of Telligent’s required user fields are present.

  • Add columns for out-of-the-box fields to the CSV.

  • Add custom profile field columns to the CSV.

  • Specify roles that the users should be added to.

  • Specify the manager for each user.



Creating a Valid CSV



A valid CSV (Comma Separated Values) file contains rows of data, with each value in a row delimited by a comma.  And for each value that contains a comma within the value, or a new line, it is required that the value be surrounded by double-quotes.  And for double-quoted values that contain double-quotes, you must double the double-quotes.  And for occasions where double-quotes aren’t required, you can still use them any way you want.  Below are some examples.



Row 1,Value One,Value Two,Value Three

Row 2,"Value One","Value Two","Value Three"

Row 3,Value One,Value Two,"Value Three has a comma, in it"

Row 4,Value One,Value Two,"Value Three has a quote"" in it"

Row 5,Value One,Value Two,"Value Three has a newline

 in it”



Character encoding is important, and when possible use UTF-8 or plain old ASCII.  This is especially true when using non-English alphabet characters.  If you are seeing strange characters in Telligent after importing data, the character encoding of your data file is likely the cause.

For Microsoft Excel users, be on the lookout for Microsoft-specific characters because they often won’t translate well.  This includes smart quotes, apostrophes, ellipses, and em-dashes.  This can occur when you copy-paste data from MS Word or MS Excel.  If after importing user data into Telligent you see unknown characters in place of quotes (single and double), ellipses, or dashes, then you will want to review your source data for Microsoft-specific characters.

The key to the user importer being able to read your data is the column headings you provide in the CSV file.

Provide Locator Column(s) When Updating Users

Telligent provides three ways to lookup an existing user; by their ID, by their username, and by their email address.  When you provide one or more locator columns in the CSV file the tool will try each of these to attempt to load an existing user.  If it finds a matching user, the record will be updated, and no match is found then a new user will be created.



The three Locator columns headings are id, username, and privateEmail.  Add one or more of these columns to your CSV like in the example below.

 

username

password

profile.firstname

profile.lastname

privateEmail

_test1

FUFU_292

Leslie

Vaines

lvaines@socialedgeconsulting.com

_test2

DYdsY!O@T

Hilly

Pletts

hpletts1@socialedgeconsulting.com

_test3

6913HK27

Monro

Kik

mkik2@socialedgeconsulting.com

_test4

JKD97823joed

Kristy

Bjerkan

kbjerkan@socialedgeconsulting.com

_test5

UKG(28jJ_!

Toddy

Baggett

tbaggett4@socialedgeconsulting.com

_test6

G7-Hgh2hdg

Juliet

Dewis

jdewis0@socialedgeconsulting.com

 

 

Provide Required Columns When Creating Users

When we say “required” fields we are talking about the minimum set of fields that Telligent needs to create a new user record.  The required fields are username, password and privateEmail.  The example CSV below includes the minimum fields required to create new user records.

 

username

password

profile.firstname

profile.lastname

privateEmail

_test1

FUFU_292

Leslie

Vaines

lvaines@socialedgeconsulting.com

_test2

DYdsY!O@T

Hilly

Pletts

hpletts1@socialedgeconsulting.com

_test3

6913HK27

Monro

Kik

mkik2@socialedgeconsulting.com

_test4

JKD97823joed

Kristy

Bjerkan

kbjerkan@socialedgeconsulting.com

_test5

UKG(28jJ_!

Toddy

Baggett

tbaggett4@socialedgeconsulting.com

_test6

G7-Hgh2hdg

Juliet

Dewis

jdewis0@socialedgeconsulting.com

 

 

 

Provide Required Columns When Creating Users



The following Out of the Box profile fields are supported by the user importer.

 

Profile Field

Description

ID

The numeric ID of the user.  This only exists for existing user accounts.  It can be used as a Locator to match an existing record and is not updatable.

Username

The username for the user.  This is required when creating new users and can also be used as a Locator for matching existing user accounts for updates.

Password

The password for the user.  This is required when creating new users.

accountStatus

This is a string property for the user's account status. May have next values:

  • ApprovalPending

  • Approved

  • Banned

  • Disapproved

enabled

This is a shortcut for field accountStatus. “True” means accountStatus is Approved, overwice - Disapproved.

language

This is the locale setting for the user.  The locale values include ISO 639-1 values, which are two-character codes that indicate the local.  This includes “en” for English, “fr” for French, and “zh” for Chinese.  You can optionally add to this an underscore and a ISO 3166-1 two-character country code.  For example “en_US” is used to signify US English, and “en_GB” for British English.  Please refer to the Wikipedia pages for ISO 639-1 and ISO 3166-1 for a list of these codes.

https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes

https://en.wikipedia.org/wiki/ISO_3166-1

location

A text field used to specify the location (office, geographic area, etc.) for the user.

timezone

Telligent supports the time zones listed in the IANA Time Zone database.   Examples for the United States include; “America/New_York”, “America/Chicago”, and “America/Los_Angeles”.  Many deprecated IANA zone codes will also work, like “EST5EDT” and “CST6CDT”.  See the Wikipedia link below for a list of these.

privateEmail

The user’s primary email address.  This is required for the creation of a user.  This is different from a custom profile field of type “Email”.



Adding Columns for Other Custom Profile Fields

Use this format when adding columns for custom profile fields. 



Comma-separated List and Multiple Select - have to be defined in one cell with comma-separated values. 

Note: you can’t use commas in the field values!



profile.{fieldkey}:{type}

         Replace {fieldkey} with the name of the profile field in Telligent.

         Replace type with next possible values: bool, number or decimal.

Most profile fields by default have string values, but checkboxes have booleans, numbers are numbers and decimals are decimals.

 

id

profile.firstname

profile.employee:bool

profile.roomNumber:decimal

profile.rating:number

1020

Leslie

True

1

15

1384

Hilly

True

256

17.4

2874

Monro

False

87

0.22

 

 

Adding User to Roles

The following column can be used to add users to one or more permission groups.

 

roles

           A comma separated list of role names to add the user to.

Note: commas in role names are not supported!

 

Column Options



Column options allow you to set options on how the user importer works for each column.  Options are added to the column heading by separating options with colons (:).



For example, if you wanted to apply ‘option1’ and ‘option2’ to the username column, you would use the heading “username:option1:option2”.



If you are using column options, when you run the user importer it will print out a summary of column heading that is using options.  In addition it will validate the options to avoid errors caused by mis-typing an option name.  If there are any validation errors with the options they will be displayed and the program will exit.



The following is a list of column options.

 

Column Option

Description

Examples

noupdate

This option informs the application to only apply the value for new user records, and to not update the value if the user already exists.  For example, if your data includes a password column you may want to ensure that the password is only set for newly created user accounts, and to leave the current value intact on existing ones.  To enact this option for passwords you would use the column heading password:noupdate.  The noupdate option has no effect when used with the roles or manager.* column headings.

password:noupdate

username:noupdate

Random

This option informs the application to ignore values of columns but generate random string 12-20 symbols. Common usage is for random passwords.

password:random



number

decimal

bool

These options are used with custom profile fields with non-string types.

If you want to update profile fields like “Specify your weight” or “Do you have a dog?” accordingly you may use number and bool fields, so you have to add options for those fields. 

profile.weight:number

profile.dog:bool



 

 

Steps to Run the Report



  1. Make sure the following files are under under the same folder on your computer:

Application.properties

.jar

.csv

 

  1. Update the application.properties file to include the following highlighted in yellow.



  1. Check your .csv file for the correct required fields and profile fields



 

  1. Open up the “command prompt” on your computer add the line: java -jar telligent-userimporter-1.0.0.jar, hit return. The file will then run

 

 

FAQs



Q: I see warnings when running the importer, what do they mean?



A: If you are using Java 9 or Java 10 you will see a warning like the one below.

WARNING: An illegal reflective access operation has occurred

WARNING: Illegal reflective access by ...

WARNING: Please consider reporting this to the maintainers of ...

WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations

WARNING: All illegal access operations will be denied in a future release



These warnings are due to a new feature that was introduced into the Java 9, which was released in September of 2017.  At this time some widely used Java libraries trigger this warning due to how they work.  The vendors of these libraries are working on making changes that will fix this warning, but as of now they have not been released.



If you are using Java 9 or Java 10 these warnings represent no danger and are simply an annoyance.  Java 11 will be released in late 2018, and at present time there is no indication that this tool will stop working with that version.

 

 

 

 

 

 

Support

Need support or want to talk to us?  Please send an email to:

support@socialedgeoncuslting.com