Creation of users in Activate LMS can be done via automatic user synchronization with your database of users. This article will focus on implementation and configuration of the automatic user sync. The following flowchart will give you an quick overview of how user sync works with Activate LMS. In this example we're using AD, but it can also be done using other software that can export a list of your users in a .csv file.

The configuration of an user sync requires assistance from an Activate LMS consultant, so please contact us using this form to get in contact with us.

Configuration of the PowerShell Script

In the provided PowerShell Script there is a number of comments, which indicates where you should edit the script to fit your situation.

$ADServer: Address of the server where your AD services is installed.
$SearchBaseList: A comma separated list of OU (organisational unitsB) from where users should be exported from.
$path: The absolute path of the location where you wish to save the generated .csv file. This path must match folder name specified in the sync application's config file:
$CSVFile: This indicates the name of the .csv, which will be generated. This name should also match the file name specified in the sync application's config file:
$prop: Indicates which fields should be collected from users (e.g. "Givenname","Surname","Mail","Division"). Please note that there must be a field referring to a users email, since this will be used as the user's username. Also note that a email address can only occur once. If there are duplicate mails the sync application fail and no users will be uploaded to your Activate LMS. You can choose to import some kind of division, department or location for dividing users in organisations in your Activate LMS. Please refer to this article to get more information using batch import in Activate LMS.
$CSVReady > Select-object : This field indicates how your .csv file will be structured. We recommend to visit this article, to get an idea of how to structure your users in Activate LMS.
$CSVReady: Lastly this command will write data to the new .csv file. To get more information about the export-csv command please refer to Microsoft's own documentation: https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/export-CSV?view=powershell-5.1

The Sync Application

Requirements

Microsoft .NET Framework 4.5
To be "Run as Administrator" when executed
Server should have access to the internet from port 80, to communicate with webservices on your Activate LMS.

Documentation

Basically the Sync Application will do a check to see if there's difference (Δ delta) between the previous and current run of the PowerShell script. The application will first look for a file in your Upload folder - and if there's none the program will terminate and do nothing. If the application registers a file in the Upload folder, the file will be copied to the folder _System/Current. Now the application will check this new data with data found in _System/Previous (which contains the data from the previous run). Any differences will be written to users.xml in the _System/Result folder. This file will then be converted to .xsl (this is needed for Activate LMS to be able read it) and afterwards uploaded to your Activate LMS, which will apply the changes automatically. Lastly the file in _System/Current will be moved to _System/Previous.

Configuration of the Sync Application

Configuration will be done by editing the provided ActivateLms.ADImporter.exe.config file. This file will have comments to help you fill out values correctly. Please note that some values must match values indicated in the PowerShell script.

activateLms/settings/application/@name: Refers to the name of your Activate LMS. Will be provided by one of our consultants at setup. This value is mandatory.
activateLms/settings/application/@key: Refers to the application key of your Activate LMS. Will be provided by one of our consultants at setup. This value is mandatory.
activateLms/settings/application/@useSecureServiceConnection: Indicates whether or not you're using https when communicating with your Activate LMS. The default value is true (indicating that https will be used).
activateLms/settings/application/@debug: Indicates whether or not use wish a verbose log when debugging. The default value is false (indicating you wish a limited debug log).
activateLms/settings/application/@uploadToWebservice: Indicates whether you wish to upload data to your Activate LMS or not. This can be very helpful during the initial tinkering. The default value of this is true (indicating that data will be uploaded to your Activate LMS).
activateLms/settings/files/@uploadFolder: Indicates the location of the folder where the .csv file saved by the PowerShell script is. The path will be relative to the location of ActivateLms.ADImporter.exe. Please make sure that this refers to the same folder indicated in the Power Shell script ($path).
activateLms/settings/files/@uploadFileName: Refers to the name of the .csv file, saved by the PowerShell script ($CSVFile). Please make sure that this refers to the same file indicated in the Power Shell script ($CSVfile).
activateLms/settings/files/@xslfilepath: Path and filename of the generated .xsl file that will be send to your Activate LMS. The path is relative to ActivateLms.ADImporter.exe.
activateLms/settings/CSV/@incommingSeparator: Indicates what character that is used to seperate fields in the .csv file uploaded by the PowerShell script. Default is ";", meaning ; is used to separate fields.

Please note that the following values are only used if you wish to use .csv as the outgoing format to your Activate LMS instead of .xsl. Although this is not recommended, but can be used in rare occasions.

activateLms/settings/CSV/@outgoingSeparator: Indicates what character that is used to seperate fields in the .csv uploaded to your Activate LMS. Default is ";", meaning ; is used to separate fields. Please note that this is not used if you use .xsl to generate the outgoing file to your Activate LMS.
activateLms/settings/CSV/@quotevalues: Indicates whether to use quotes for values in the .csv file. Default is false (indicating that you don't wish to use quotes around values).

Configuration of connection to Activate LMS

In ActivateLms.ADImporter.exe.config you need to specify the URL of a Activate LMS API. In the provided file you can see to different options: an address to our test server and one to our live server. Initially the address of live server will be out-commented. We recommend you to keep these settings until you're sure everything is working. When you're sure everything is right, you can put the comment tags () around the demo server address instead:

Configuration of xml2csv.xslt

The .xslt file can be found in _System/XSLT/. This file is used to generate the final outgoing data for your Activate LMS. This gives us an opportunity to validate and modify data to our needs, before it is finally uploaded. By default this file will have the following fields in the beginning of the file:

The fields you need to edit are the following:

organisationsprefix: Indicates which root organisation in your Activate LMS user should be connected to. This value will be specified by your Activate LMS consultant.
emptyOrganisation: Indicates which organisation users will be put in, if no organisation is specified.
defaultLearningProfile: Indicates which learning profile users will have by default.
newLearningProfile: Indicates which learning profiles users will have if they haven't been registered in a previous run.

These are just some of the default fields, but if needed a lot more customization can be done in this file.

Debugging

Logging can be configured in log4net.config. In general logging is written to two different logs:

Info.log, which contains general info and information (how many users were created/updated etc.) about how a run went.
Error.log, which contains fatal errors including details. This log can also be sent to your email, at runtime when it happens, making you up-to-date if something fatal happens. If you wish to get logs by mail you need to do the following:
1. Remove the comment around appender in the root node:
2. You also need to remove the comment around this appender node further down the file:
  
  In this block you must also specify the following fields:
  - to: The email you wish to send the log to
  - from: The email you wish to send the log from
  - subject: The text that will be set in the subject field of the email
  - smtpHost: The smtp-server from which the email will be send from

More information about logging can be found here: https://logging.apache.org/log4net/

Testing your User Sync implementation

After configuring the provided PowerShell Script and User Sync application, it is now time to test your implementation locally! We recommend that activateLms/settings/application/@uploadToWebservice in the PowerShell Script is set to false for now.

After running the PowerShell script, you can verify if there's generated a .csv file at the specified location.
If there is a file, it is time to run ActivateLms.ADImporter.exe.
If all goes well, you should be able to find a copy of the generated .csv file in _System\Previous and also two new files in _System\Result:
1. users.xml, which has all users that needs to be uploaded to your Activate LMS
2. a .csv file containing the data that needs to be send to your Activate LMS
Great succes! If you can check off the above, everything should work as intended. If you need to redo the test, you must delete the .csv file in _System\Previous. After this you can safely test your implementation again.