What Is sFTP?
Secure File Transfer Protocol, sFTP for short, is a more secure version of the File Transfer Protocol, a popular method of transferring files between two remote systems. sFTP facilitates data transfer over a Secure Shell (SSH) data stream.
sFTP at Learning
sFTP is a secure method for automating the creation, updating, and archiving of users in the Learning application. Uploaded user data can include useful attributes, such as standard and custom fields, to help managers effectively group Learning users.
While not a real-time integration, user data can be transmitted and processed as frequently as every hour.
When adding an sFTP integration to a Learning setup with active users, sFTP will connect to existing users by matching their email address as the unique identifier.
Optional
An optional feature available to customers is the ability to automatically generate a manager hierarchy in Learning.
This feature allows users to be placed into groups for each manager listed in the user file. It can then be used to grant the managers automatic ownership of their direct reports as well as the direct reports of managers beneath them in the hierarchy
Important Notes
This integration acts as a one-way street. User data from the file can be securely uploaded into Learning, but edits made within the Learning application do not transfer back. Learning asks with this integration, all user updates are made only in the file.
To help avoid any issues with user provisioning, it's important (especially for hierarchy (batch) sFTP syncs) users aren't added via single sign-on (SSO provisioning). If a company is running a hierarchy (batch) sFTP sync they should always have SSO provisioning turned off.
Using sFTP at Learning
When inquiring about sFTP, customers are expected to develop a process wherein an automatically generated CSV “flat file” with user data (from a user data source of their choosing) is delivered through sFTP to a folder owned by Learning.
Important Note: If a daily file upload is not something a customer is able to do for this integration, it is recommended to use the Bulk User Importer.
The source of the user data is most frequently an HRIS but can be any database containing the user data that a customer needs to effectively group users in Learning, as long as a customer can automatically generate a file
If there are multiple different sources, Learning can accommodate combining multiple files into one setup. The only requirement is for the entire process to be automated. There should be no manual intervention on the customer’s part to upload a file once the setup is complete.
After the file is delivered to the Learning folder by the customer’s automation, Learning collects and processes the file to create, update, and archive users, and will retain all uploaded files for historical records.
If encryption is required, Learning can provide customers with a public encryption key.
Important Note: Many customers use internal technical resources to accomplish this customer-side automation, and many need to seek help from their HRIS. Learning by Seismic is also able to provide paid services to this end as well. You can reach out to your account manager for more information.
sFTP Set-Up Process Outline
Step 1: Review sFTP article and plan internally
Review this documentation, and decide between this standard sFTP option and the sFTP with Hierarchies option.
Reach out to your internal resources and/or HRIS consultants to begin conversations around automating the file creation and delivery using details from this article.
Step 2: Contact your Learning teammates
Reach out to your Account Manager and one of the following Learning teammates:
Solution Consultant (if you are actively implementing Learning).
Technical Account Manager (if you have a TAM package).
Learning Support (support@lessonly.com or by using the in-app chat feature).
Send the following items to the designated teammate:
The customer's technical contact (integration builder) email address.
The customer's technical contact (integration builder) SMS text phone number - for a secure account password exchange.
Step 3: Creation of an sFTP Account
Learning will create sFTP folders and an account through our secure third-party service.
Once completed, we’ll send the login username and password to the technical contact.
If encryption is required, we’ll send the public encryption key to the technical contact.
Step 4: Building and Uploading of Test Files
The customer’s technical contact will design the automated creation and delivery of the file to the /test folder.
File specifications are as follows:
CSV file with UTF-8 encoding
Without BOM
File names:
Please include the company name and a date/time stamp in the file name.
Each file should have a consistent beginning to the name
e.g. Customer_LearningFile_08302021, Customer_LearningFile_08312021, Customer_LearningFile_09012021...
Learning uses this constant to automatically search for the most recently uploaded file beginning with “Customer_LearningFile_”
Files must end in .csv (please don’t include the date/time stamp after the .csv).
If encryption is required, the file extension in the name must be .pgp
Column headers are available on the following templates:
sFTP CSV template - Standard sFTP
sFTP with hierarchy CSV template - sFTP with Hierarchies
The only difference is the inclusion of the Manager’s Ext. ID column which must correspond to a value in the “Ext. ID” column for hierarchies to function.
Managers may not report to themself for hierarchies to function.
See the section below titled “Notes on Learning Roles” for options on how to control Learning Role assignments for users. Report back to your Learning teammates with your preferred option.
The file should include the full active population in every file (both user rows and column contents), not just the deltas/changes. With this integration, if a user drops off of the file from one run to the next, they will be archived automatically in Learning.
Important Note:You can maintain additional users manually within Learning as long as the sFTP integration never touches those users (they’re never included in the file). This is common for users that don’t exist in the HRIS/data source but need Learning accounts.Any custom fields need to follow the “Custom: [Custom Field Name]” format, e.g. “Custom: Region” would create and populate a custom field in Learning called “Region.” You can add multiple custom fields.
The only required columns are Ext. ID, Name, and Email. All other columns should be included only if needed, and column order does not matter.
If commas “,” are present in the text you will need to wrap all fields in the column in quotes.
Non-English alphabet characters are accepted.
Any of the below characters are Invalid and would prompt the sync to fail:
! # $ % ^ & * ( ) + = [ ] { } ? √ © √º ∂ ±
If you are unable to modify column headers, they can be remapped on the Learning side if communicated to the Learning teammates.
Important Note:The customer Learning admins will need to inform their technical contacts as to which fields are needed in the Learning file. They should help identify which HR fields contain the data they need in Learning and communicate how that should map to a Standard or Custom Learning field.Once a test file has been generated, drop the file into the /test folder and inform your Learning teammates it's ready to be tested. Please include any field mapping instructions if you were unable to match the column names in the template file.
Step 5: Mapping
Learning will complete the integration build and field mapping. If any modifications need to be made by the customer, they’ll be communicated at this stage.
Step 6: Begin Automatic Delivery
Once your Learning teammates give the go-ahead, begin automatic delivery to the /production folder.
When the files have been processed, they’ll be moved to the /production/processed folder by our integration for your records.
Notes on Learning Roles
In the absence of any Role assignment automation, new users are always given the role of Learner and can be upgraded to a higher role by anyone with an Admin Role.
Automatic Role assignment options are:
Include a column in the file specifying the user’s Learning Role with the column header Role.
This overrides any role changes made manually in-app for added security
This option involves either:
The creation of some logic in the customer’s file creation automation to apply entries to the Role column based on some other HR attributes, or
Will require a new field in your HRIS/user data source specifically for Learning Role with the Role names as entries
If using sFTP with Hierarchies, anyone with a people-group being created for them can optionally be auto-granted a Manager Role.
If this option is selected, you might need some exceptions to that rule (e.g. users who should be an Admin or Creator instead of a Manager Role). If that’s the case, supply your Learning teammates with a list of those exceptions to prevent this optional automation from demoting Admins down to a Manager Role.
These exceptions will be hard-coded on the Learning integration, and are not self-service or customer-facing. If the number of exceptions is large or is likely to grow, then option #1 above is preferred
User Role Updates with sFTP
New Users
The role for new users, by default, is set to a learner, unless a Role column has been included in the file.
Existing Users
Any existing users maintain their role unless Learning is running a custom setup for them. This needs to be discussed during the setup process. Users already in Learning who are also included in a file are recognized during the sync by their email.
Archiving Users
There are 2 options for archiving users via sFTP.
Customers can include an Archived column in the file, and use the values of Yes and No to specify which users should and should not be archived.
Some HRIS systems exclude inactive users. This could determine whether a user should be archived based on whether they appear in the file.
Role Management
Roles in Learning can be managed through sFTP. There are two routes for managing roles.
The customer can create a column in the .CSV file specifying the role of the user.
The customer can leverage existing columns inside the .CSV and provide Learning's team with the logic on how to code their CSV file (we call these "Role Rules").
Once role management is elected as a strategy, any role changes must be made via sFTP. If an admin were to make a role change in Learning (not via SFTP), this change would revert back to the role indicated in the CSV file.
Customers can choose to manage roles completely outside of sFTP if they have no role column or role rules setup.
How long does it take to get the sFTP integration up and running?
Completion times average approximately 2 weeks. The Learning team is at the hands of the technical resource and this time range can vary based on consistent communication.
Questions? Contact the Support team at support@lessonly.com