Audience: ClassLink Administrator
Valid sources include Microsoft Active Directory, CSV (comma-separated values) files, and ClassLink OneRoster. Each source requires different forms of credentials or setup.
- CSV Files
- Google Sheets
- ClassLink Roster Server
- ODBC (Open Database Connectivity)
- Microsoft Active Directory
CSV files can be uploaded to OneSync by adding CSV files to a OneSync directory. This directory is automatically generated by your installer and can be located at C:\ClassLink OneSync. You can download a Sample CSV at the bottom of this article or create your own CSV file using programs such as, but not limited to, NotePad or Microsoft Excel. The screenshots below illustrate the same set of CSV data, viewed in Notepad versus Excel.
Note: When using Microsoft Excel to edit and format your CSV data, you must save your file as type "CSV (Comma delimited)".
When creating a CSV Source there are three different options for how to retrieve the CSV:
- Local: This option will prompt a drop down that will contain all the CSV files within the ClassLink OneSync folder on your local computer.
- SFTP (Secure File Transfer Protocol): This protocol will prompt for credentials to the SFTP Server that you have set up. This protocol will download a copy into your local ClassLink OneSync folder once the source is created.
- FTPS (File Transfer Protocol Secure): Similar to SFTP this protocol will prompt for credentials to the FTPS Server that you are connecting to. This protocol will also download a copy into your local ClassLink OneSync folder.
- Network Share: Similar to SFTP and FTPS Network Share will prompt for credentials to the Network share and will allow you to download CSV files over a network.
Here's an example of what a Network Share CSV source looks like:
The required properties are:
- Domain: The domain that this file is being retrieved from. OneSync must be on the same domain to retrieve the file.
- Username: A username that is on the domain specified.
- Password: The password for the user.
- Base Path: The basepath of Network Share, which will be the Network Share path for the computer or server that the file is being retrieved from.
- File Path: The path of the file being retrieved which can be a path of directories for which the file is in.
CSV sources also possess a few additional features. You can download the current source CSV file. This will include all of the headers and data from the latest CSV file. You can also upload a new CSV file to replace a source CSV file. To upload a new CSV, it must contain the same headers that are mapped to in the original CSV. Uploading a new CSV will replace all of the old source CSV's users. These old users will be disabled in all applicable destinations.
OneSync can also handle non-standard CSV files including those with no headers and those with duplicate headers. While creating a CSV source, you have the option to specify whether or not the "File contains headers?". If the file does not contain headers, OneSync will generate numbered headers for each field. These headers will then be inserted into the file. Once you create and save a source, you cannot change the setting specifying whether or not the file contains headers.
While creating a CSV source, you can also specify whether or not to "Concatenate data of duplicate headers?". Selecting No will block you from creating the source. Selecting Yes will allow you to map from the columns containing duplicate headers. When you import from the CSV, the data from the duplicate headers will be concatenated into a single string with the original data separated by commas.
This will allow you import your spreadsheet data into OneSync. Similar to GSuite, Google Sheets will need its own API key and secret. To create a new API key and secret for Google Sheets read over our Authorization & API Registration document by clicking here.
. When creating a google sheet you will be required to fill in the following fields:
- Source Name: This will be the name of your Google Sheets source in OneSync
- Source Type: This will be the type of source (in this case Google Sheets)
- Authorization Credential: The authorization credentials that you have set up in the Google Developers Console. You will need to sign into the account that has access to this Google Sheet.
- Sheet URL: The URL of the Google Sheet (make sure to use the entire URL)
- Sheet Name: A drop down that will list all of the available Sheets on that Google Sheet
- Description: This provides a description for your OneSync source
- Cell Range: You have the option to specify a cell range of the particular sheet selected. For example if you were to use A1:D15 OneSync would read from range of cell A1 to the cell D1.
Once setup you will be able to import from this Google Sheet similar to how you would import from a CSV source.
For security purposes OneSync will only accept Google Sheets that are not publicly accessible, this means that the Google user that is authorizing must have full access to the Google Sheet. For security reasons it is best to only import Google Sheets that you have created or a Sheet that has been created and managed by somebody within your organization.
ClassLink Roster Server
OneSync can import data from your Roster Server but requires the server's URL, API Key, and Secret. To find these credentials, log into your Roster Server account through the ClassLink portal or here. You can find the URL at the top right of any page, next to the log out button.
Note: When using the ClassLink Roster Server, the suffix “/ims/oneroster/v1p1” will be added to the end of the URL if it does not already specify it. For example, the URL below will be formatted as "https://sandbox-demo-v2.oneroster.com/ims/oneroster/v1p1". If you are using another OneRoster compliant source, be sure to use the full path to the /users API.
You can then find the API Key & Secret by navigating to the Applications page, finding the ClassLink app (make sure it has full permissions) and clicking the three dots in the Actions column. In the dropdown list, click API Key and Secret for the current Key and Secret.
Note: If your server is ever reset, the Key and secret will change. The Key and Secret stored in OneSync will not auto-refresh, so you will need to update the credentials there as well.
ODBC (Open Database Connectivity)
ODBC is an API for accessing database management systems, which allows OneSync to connect and import from your database directly. You can import one table per source. To use this source type, you must first set up a Database Connection:
- You can setup a database connection in OS Settings
- From Source Details click the blue +ADD DATABASE CONNECTION button and a slide over will appear. You will need your database username, password, port number, and schema name. The host IP will be the database's IP address. If you are running it from your local machine the IP will be 127.0.0.1. Once a connection has been created, you can select the connection when creating an ODBC source.
To select users to import, you must include a query for those users (e.g. "SELECT * FROM [yourTableName];"). This query will not only be used to select users but to filter them as well. Import Filters are not included in ODBC sources since filtering can be accomplished with the proper query.
Note: You must download drivers for ODBC here.
Microsoft Active Directory
Active Directory requires credentials including a username, password, protocol, domain, base path, and port number. You can check your connection status by clicking the Test Connection button. The default values for protocol and port number are LDAP and 389, respectively. The domain is the user’s personal preference. The base path is the distinguished name of the domain, including the domain component (DC), and excluding the common name (CN) and organization units (OU).
Once you've connected to your Active Directory, you can proceed to the Source Mappings tab where you can filter users to be imported. Click Filter By OUs to select the specific OUs from which users are to be imported.
Updated: Oct 2019