Using the Built-in Bulk Import Utility in ACP to Provision Audio Profiles
In order to create a user base programmatically in Adobe Connect and also provision audio profiles at the same time, we have an Audio Profile Import Utility built to run in Adobe Air here. However, you can actually use the built-in Import functionality in the Administrators>Users and Groups area of Adobe Connect to do the exact same thing. This is a ‘backdoor’ way of creating profiles.
Introduction:
The bulk upload feature in Adobe Connect (Administration > Users and Groups > Import) provides the functionality to create telephony profiles for a number of Connect users at the same time. This makes it extremely easy for a Connect administrator to provision telephony profiles for a large number of users via an already existing list (in CSV format). This can be new users or existing users.
At present Connect provides a user-interface (My Profile-> My Audio Profile-> New Profile) where a user can create his telephony profile. But with this UI option only one user profile can be created at a time and this option would take a lot of effort if the administrator wants to create telephony profiles for many users. In this case, the build-in bulk import feature would be very useful.
Feature Spec/Work-Flow:
i. In this feature, we are just extending the existing “import users” functionality. So the same CSV file which was being used for creating new users (via import users functionality), would be used to contain telephony profile information.
ii. Administrator creates a CSV text file which contains information about new user and the associated telephony profile. Administrator can choose either the adaptor-id or provider-id as parameter for creating telephony profile. Code first tries to get provider-id field and if provider-id is not present in CSV header then code looks for adaptor-id field. We are supporting adaptor-id input option because getting adaptor-id would be convenient for Administrator (also adaptor-id would be less error-prone than provider-id). CSV file should look like as follow:
(CSV Format i: Using telephony adaptor-id as csv input)
first-name, last-name, login, email, password, adaptor-id, profile-name, telephony-field-1, telephony-field-2, telephony-field-3
Mulder, Fox, fox@company.com, fox@company.com, breeze, avaya-adaptor, Avaya-profile1, x-tel-avaya-conference-number=6001, x-tel-avaya-moderator-code=7777, x-tel-avaya-participant-code=777
Scully, Dana, dana@company.com, dana@company.com, breeze, avaya-adaptor, Avaya-profile2, x-tel-avaya-conference-number=6000, x-tel-avaya-moderator-code=9090, x-tel-avaya-participant-code=909
Skinner, Walter, walter@company.com, walter@company.com, breeze, avaya-adaptor, Avaya-profile2, x-tel-avaya-conference-number=6000, x-tel-avaya-moderator-code=1234, x-tel-avaya-participant-code=123
OR
(CSV Format ii: Using telephony provider-id as csv input)
first-name, last-name, login, email, password, provider-id, profile-name, telephony-field-1, telephony-field-2, telephony-field-3
Mulder, Fox, fox@company.com, fox@company.com, breeze, 11035, Avaya-profile1, x-tel-avaya-conference-number=6001, x-tel-avaya-moderator-code=7777, x-tel-avaya-participant-code=777
First line is the header which specifies different fields required for user-entry (new telephony fields are written in green). After the header-line, user information can be written in new lines. Number of fields in header and values in user’s entry should be exactly same.
In user’s entry telephony-field and value should be separated by “=” delimiter.
iii. Number of telephony fields could be different for different adaptors, so one CSV file should have entries specific to only one adaptor. Above example contains Avaya adaptor specific fields( like “x-tel-avaya-conference-number”), similarly Premiere Adaptor can have different telephony fields. There is no restriction on number of telephony fields.
Note- How to get telephony profile information?:
Administrator can get the adaptor-id and provider-id using the “telephony-provider-list” api. Alternatively adaptor-id can be taken directly from telephony-setting.xml.
Telephony fields of an adaptor can be found using “telephony-provider-field-list” api. Choose field-ids for those telephony-fields which are displayed in UI of (My Profile-> My Audio Profile-> New Profile).
iv. Once CSV file is prepared, administrator can go to Administration->Users and Groups->Import. Select the import type as “Create New Users”. Browse CSV file and click upload button. (Look at the snapshot attached in the bottom).
v. After upload, Connect creates new users with telephony profiles.
vi. We can also create new telephony profile for existing users. But we are not going to provide any extra radio button as such “Create profile for existing Users”. To create profiles for existing users, you use the fourth Import option, which is ‘Add Existing Users to a Group’. This will allow you to take a csv of existing users, and create telephony profiles for them in bulk. You need to add them to an existing group you would have already created (‘Imported Users’ for example).
vii. Multiple Telephony Profile creation for a user: If we want to create multiple telephony profiles (of same adaptor) for a user, just provide same user’s entry in multiple lines with different telephony profile information.
viii. As per error handling in the existing Connect code, if more than 10 errors are found in the CSV file then we stop the operation and don’t process next line. User gets an error message saying “The import operation exceeded the maximum number of errors and was aborted. All valid entries prior to the abort have been commited to the system. Invalid lines were found in the CSV import file. List of 10 invalid entries:…” . As we don’t process any entry after 10th error, we don’t know whether there would be some more error in the file. Once user corrects first 10 errors and uploads file again, we would show him next errors in files.
Technical Spec:
i. We would use the existing code which is being used to create new users from CSV file.
ii CSV file would be uploaded using “csv-import” api (PrincipalManager.java).
iii Following fields are considered as telephony fields (which would be sent in telephony-profile-update api):
– provider-id/adaptor-id
– profile-name,
– Fields with prefix: “telephony-field-“
iv. If CSV file contains provider-id field then code directly uses it for calling telephony api. If provider-id is not given then code looks for adaptor-id and fetches provider-id for given adaptor-id.
v. After parsing an entry (line), “principal-update” api would be called to create a new user. If user doesn’t exist then new user would be created else principal id of the existing user would be used for further operation.
vi. Once we get the principal-id of new user, we would call “telephony-profile-update” api (TelephonyManager.java) with telephony map created in step iii.
vii. After this telephony-profile-update api would create a profile for the user.
viii. Error Handling: If any errors occur while parsing CSV file or calling any internal api, we add this entry(line) in an error-array. If the size of this array reaches max error limit of 10 then we stop the operation and don’t parse further entries. Administrator would get the error message with a list of 10 invalid entries.
Assumptions/Limitations:
i. One CSV file upload would require profile creation for only one Adaptor. To create profile for different adaptor, separate CSV file should be uploaded.
ii. Existing telephony profile can’t be edited using this feature. Only new telephony profiles can be created.
iii. As we are using “=” character as delimiter to identify telephony-filed name and value, the delimiter (=) shouldn’t be part of the telephony field’s name or value.
Troubleshooting:
i. Make sure the number of fields in header and in the user-entry are exactly same.
ii. Profile-name should be unique for a user. Make sure the user doesn’t have any existing telephony profile with same profile-name.
iii. In user entry, telephony-field and value should be separated by single “=” delimiter.
iv. No blank line in CSV file.
Screenshot below:
