The Form LMS User API is a REST API that allows an external application to manage Form LMS users, organisation units and groups, saving time and resources that would otherwise be spent on manual updates.
Roles required: Site admin, admin and the IT team from your organisation
Watch this short demo of the API:
Note: CSV files are used in the above video for demonstrative purposes. In reality, each row of data delivered back to Form LMS via the API will be through a bespoke integration developed by your IT team.
View the API endpoint documentation (OpenAPI v3 standard):
View the API specification documentation
Contents
- Overview of the setup process
- Enabling the API and generating an API key
- Integrating the API with your application
- Creating organisation units and groups
- Creating auto-enrolments and workflows
- Creating user fields
- Inviting users
- Data maintenance: Reading and updating
- Disabling the API
Overview of the setup process
Setting up the API requires a few steps:
| Where | Step |
|---|---|
| Form LMS | Turn on the API and generate an API key |
| Your application | Integrate the API |
| Your application | Create organisation units, groups and user fields (via API) |
| Form LMS | Create auto-enrolment rules, workflows and user fields (if required) |
| Your application | Invite users (via API) |
Initial setup diagram
Please view the following sections for detailed setup steps.
💡Important
- Prior to any setup, the API service must be switched on for your account by our helpdesk team.
- We highly recommend setting up the API on newly created workspaces without existing users, groups or organisation units to prevent data inconsistencies.
- When the API is turned on, manual operations on users, organisation units and groups are disabled.
- To ensure proper identification, we recommend using email addresses in API requests as users can be identified using both their IDs and email addresses.
- If the API is turned off after being enabled, any existing organisation units or groups will be deleted from the workspace - this is irreversible.
Enabling the API and generating an API key
To get started with the API, you will need to turn it on and create an API key:
- Go to: Setup → Site settings → API integration
- Select the API toggle to turn the API on
- Select Generate key to create an API key
You will need to have the Site admin role on your user to do this.
💡Helpful tips
- If you don't have access to the API Integration tab, please contact Me Learning support to have the API service enabled on your site.
- An API key is required to gain access to the API endpoints, so it must be used in all requests.
- As the API key grants access to sensitive data, please store it securely.
- If there is a chance that your API key has been compromised, generate a new one - the previous one will be automatically deactivated.
- You can have up to two concurrent active API keys to enable you to replace keys without a break in processing requests.
Integrating the API with your application
The team in charge of the application's IT will be responsible for integrating the API into the application. They will call the API when certain actions happen within your application. For example, when a new user is added in the application, they will make an API call to invite the user to Form LMS.
To ensure that the integration process goes smoothly and does not affect any of your current LMS users, we suggest setting up a test workspace for the IT team. This will allow them to test the API before implementing it in the live environment.
Creating organisation units and groups
Form LMS supports two ways of aggregating user profiles within a workspace: organisation units and groups.
While groups are open containers without a fixed structure, organisation units are designed to reflect the departmental structure in the form of a tree. All organisation units have roots in the workspace itself and as many child units as necessary.
Use the API to create your groups and organisations.
Creating auto-enrolments and workflows
In Form LMS, both organisation units and groups can be utilised to facilitate automatic enrolments and workflow automation rules. However, these functions must be set up by administrators within Form LMS itself. From the perspective of the the API, it is crucial to understand how these rules apply to users who are managed through the API.
If a user is invited to a group or organisation unit that has existing auto-enrolment rules, they will be automatically enrolled in the courses defined by those rules. Similarly, if a user is moved between organisation units or groups, they will receive enrolments as specified by the rules set for the target object. Additionally, if a user completes a course that is included in a workflow rule, they will be automatically enrolled in the next course according to the relevant rule.
It is important to note that automated attempts to enrol a user may fail if there is no available course licence or if the user is already enrolled in a target course and has not yet completed it.
Overall, by utilising the capabilities of organisation units and groups within Form LMS, administrators can establish rules for automatic enrolments and workflow automation, streamlining the process and reducing the workload for managing large groups of users.
Use Form LMS to create auto-enrolments. As an admin, go to: People → Auto-enrolments
Use Form LMS to create workflows. As an admin, go to: People → Workflows
Creating user fields
Each workspace in Form LMS can have up to to 10 custom fields. These are useful for associating custom information to a user (e.g. Job Title, payroll number, etc.).
Use Form LMS to create user fields. Go to: Setup → Site settings → User fields
Inviting users
A simplified overview of the user invitation process is shown in the diagram below.
Please note that there are three endpoints dedicated to managing invitations:
- api/users/invite (POST) – to create new invitations
- api/users/{userId}/invite-resend (PATCH) – to resend an invitation that has already been sent (as a reminder)
- api/users/{userId}/invite-cancel (DELETE) – to cancel a sent invitation
With the API, it is recommended to use a user's email address as their unique userId.
Data maintenance: Reading and updating
Once you've uploaded your data for the first time, you can change it whenever you need to.
Using the GET method, you can see a list of everything in the API and easily look through the details. This is really helpful when you have lots of data to manage and you need to find information quickly.
Using PATCH you can easily update user details, as well as manage your organisation units and groups.
If you want to get the most out of the API, please refer to our OpenAPI 3.0 documentation. It has useful technical information and details that can help you integrate the API into your workflow.
If you run into any problems, the Me Learning helpdesk team is always ready to help. They're very experienced and can help you use the API to streamline your work and reach your goals more efficiently.
Disabling the API
⚠️ Disabling the API
Please be advised that disabling the API feature in Form LMS will enable manual manipulation of organisation units and groups, which may result in data inconsistency. It is strongly recommended to avoid turning off the API feature unless it is no longer required for use within the workspace.