I/O Task Integration
When to use IO Task Integration
IO Task Integration is designed to connect Forma LMS with external business systems through asynchronous file exchange (e.g., CSV, XML) on a shared SFTP folder.
This approach is particularly suitable when:
- The external system does not expose APIs or only provides limited ones
- The integration needs to be simple, robust, and batch-based
- Real-time data synchronization is not required
- Large volumes of data need to be processed on a scheduled basis
When real-time interaction or event-driven logic is required, API-based integrations are recommended instead.
Use Cases
Typical use cases for IO Task Integration include:
- Automatic user import from HR systems,
- Automate user status and profiles update
- Bulk enrollment into courses or learning plans
- Data exchange with external systems (e.g., training completion records)
Check the official documentation for a full guide to the available connectors
Custom I/O activities may be analyzed and implemented upon request
Integration Flow
The typical IO Task integration flow works as follows:
- The external business system generates a data file
- The file is placed in a shared folder
- Forma LMS processes the file through the configured IO Task
- Data is imported or updated within the platform
File Management and Shared Folders
Shared Folder
File Upload to Forma Cloud
All files used for data exchange must be placed in a shared SFTP folder provided by Forma Cloud with the following path: html/files/common/iofiles
Your SFTP credentials are published in your client area, or you can ask our helpdesk team
Please verify that your systems can:
- automatically generate files in the required format
- transfer them to the shared folder (e.g., via SFTP or similar services)
File Retrieval from client system
If your system cannot automatically send files to the Forma Cloud shared folder, it is possible to:
- expose the files on a customer-managed shared folder (e.g., you company SFTP)
- request an additional service from the Forma team to automatically retrieve the files
⚠️ This additional service involves extra cost.
File format
The data file must comply with the following requirements:
- The file format must be .csv (mandatory)
- There are no strict constraints on the column separator (e.g., comma, semicolon, etc.), as long as it is consistent within the file
- Additional columns are allowed and will be ignored if not mapped in the IO Task configuration
- The column order is not strictly required during the initial setup
Once the integration procedure has been configured and activated, separator type and column structure must remain consistent over time. Changes to separators, column order or structure may cause errors in data processing.
Scheduling
The I/O task cron job is usually processed nightly at 2 am
Data Specifications
Users import and update
Creating and updating users
- Username: The username is the user's primary identifier and must be unique (e.g., the employee ID number, tax code, etc) and remain consistent over time, even if the user changes roles within the company. All automated operations will be based on this data, so it must be consistent and stable across all applications involved in the integration. It is also important that it is easy for users to remember, for example using the same username as other applications (this will also allow for SSO solutions)
- Email: Use email as forma username only if strictly required, i.e. you need it for SAML/OIDC integration and you still need it to be different from the email used for communications.
- Folder Identifier: define a field to be used to assign users to an org-chart node. Data should match exactly the org-chart code, and won't be saved to the user profile.
- Language: If no language is specified, imported users will use the default language and will see the platform in their default language when they log in. In international contexts, it's a good idea to also import the user's language and ensure the required languages are installed on the platform so they can see the platform in their native language when they log in.
- Password: the procedure can either import a password for each user from the file, or set a default password for all the users (in this case we recommend configuring mandatory password change upon first login). It is possible to send credentials to the newly imported users via email.
- Other user data: define if the system should import other data to user custom fields
Managing Node assignment
- Users can be associated to one or multiple orgchart nodes, based on a code identifying a specific orgchart. One record must be provided for each user-node association
- At every import all the orgchart association for each user will be reset and recreated, thus all users will be constantly added to the current nod association
- Missing Orgchart code: if the code for the imported user is not related to an orgchart code, the user will be placed in the root folder
Suspending users
- Suspension: users removed from the imported file will be suspended on the platform
The IO Task feature will only suspend and won't remove any user
The update procedure can't reactivate suspended users: this is to avoid conflicts with manual users management
Export of users status on courses
This connector will generate a CSV file containing a list of users and their status on courses, and can be integrated with other user information from custom fields.
Enroll users to courses
Upload a CSV file containing a list of users and course codes to automatically enroll users