- You would like to learn more about what an API connector is and how it may be of value.
- You would like to learn more about the available API calls for KnowledgeSmart.
You might have heard about API's and how they can be used to perform certain tasks or retrieve some data.
But what are these exactly, and why were they created?
Let me explain the problem with a simple, non-IT-related example.
You interact with the waiter when you go to a restaurant and order some food. You can order food and drinks, ask questions about the menu, request and pay the bill, and much more.
In this example, the waiter is shielding you from all the complicated stuff that happens behind the scenes. You don't have to worry about stoves, ovens, dishes, managing stock, or pouring drinks. Instead, he is the interface between you and all the services that a restaurant offers. In a way, the waiter can be seen as the API of the restaurant, and through this example, you intuitively understand why they are useful.
API's (Application Programmable Interface) are sets of definitions and protocols that allow software components to talk and interact with each other using a simple set of commands. Acting as messengers, APIs deliver one application's request to another and return a response in real-time.
- If the server (the application providing the resource) can do what the client (the requesting application) asked, then the API will bring back the resource needed or a status code that roughly translates into mission accomplished!
- If the server can't do what the client asked — maybe the client requested a resource that doesn't exist or that it doesn't have permission to access — then the API will return with an error message.
- Controlling access to the server in this way is crucial. Rather than give you all of a program's information or code, an API provides you only with data that has been made available to external users.
What is an API key?
An API key is a unique identifier used to authenticate calls to an API. The key is made up of a string of letters and numbers that identify the client (remember, this is the application or site making the request). The key can grant or deny that request based on the client's access permissions and track the number of requests made for usage and billing purposes.
- By restricting access only to those with keys, a company can control the number of calls made to its API and ensure that only a specific, trusted group of clients can access its server's resources.
How will you benefit?
There are many types of API's and the reasons why they are used.
Here are 4 main reasons why they are used:
- API's can be used to get access to data from third parties.
- Automatic transfer of relevant data between systems to streamline administration processes.
- Create a two-way flow of information; automate tasks between systems, and display all account and training data in one place.
- API's allow different apps and services to exchange information.
- Aside from just accessing data, API's can also be used to hide complexity and perform tasks.
- API's also offer an opportunity to boost productivity, streamline operations, foster collaboration, and strengthen transparency.
- Automate repetitive tasks between Pinnacle Series and other systems without relying on the need for technical resources (i.e. Zapier)
- API's can also be used to extend functionality (User satisfaction) – rarely can one platform satisfy and anticipate every need and expectation.
- API's can be used as gatekeepers, protecting our personal data and only giving it out to the apps we choose.
As learning and training become more of a central activity in the corporate workplace, the ability to streamline processes and deliver contextual learning is increasingly important.
It is possible to utilize API's to push and pull data between systems to perform automated functions.
Data transfers include:
- Requesting data from the server (GET)
- Posting new data to the server (POST)
- Modifying data on the server (PUT)
- Deleting data from the server (DELETE)
On the surface, an API is any method made available by a system to allow third-party access to its data and functions in a programmable way.
Advantages of an API for Learning Management Systems
The benefits of API's can range from the obvious to the not so obvious.
- It could allow employees to interact with a vast array of applications and experiences without leaving their LMS.
- It could help managers track learning activity taking place 'outside' the company LMS or other systems.
- It makes it possible to compare the learning effectiveness of different activities, possibly different services, in measurable ways.
- This includes data about all their learning activities, such as courses, mobile apps, social discussion contributions, and even offline learning experiences.
- It could help manage personal and other sensitive data, which can be hard to keep track of if stored in multiple places.
- API connectors for reporting
- This ability to collect and view data from different systems offers the opportunity to measure the impact of training as the data is viewed against project output data, for example.
- Many organizations would also be looking to automate the collection of data and then connect that with an analytics platform like Tableau or Power BI or Integrate with financial reporting and accounting systems.
- API connectors for user provisioning
- Access reliable personnel data from one source of truth.
- Enable separate internal and external login accounts.
- Provide single sign-on (SSO) to other internal systems.
- Integrate with Microsoft 365, SharePoint, and Teams.
- API uses in Learning
- Learner Data and Tracking
- One established use is tracking learner progress across different applications or systems. This allows one system to inform another system of the user's data using an API. The benefit of this approach is that the learning does not need to take place on your Learning Management System or be managed by it. It can take place on another system and be accessed via an API. This data can be consolidated in a central Learning Record Store.
- In theory, you can see how you might have hundreds of data points about an individual from many different systems. Such an approach could be used to design a personalized and adaptive learning program for individuals.
- Using API's for learner data demands an appropriate level of privacy. API's must be designed to ensure that privacy is taken into account throughout the process.
- Surfacing Content and Creating Richer Experiences
- One primary use of an API is to surface content wherever the learner needs it, such as an intranet, app, or sales academy. These content API's enhance a user's experience by providing more expansive content from a range of sources, personalized and timely, such as articles published today on a specific topic.
- By using API's, an LMS, or another system, can surface content from multiple systems seamlessly and transparently; and create a much richer experience for your user. In the old days, all the content needed to be loaded onto a particular system or LMS. This is no longer the case, as an API can pull through and surface the content relevant to the user from multiple places.
- Learner Data and Tracking
- Embedding Assessment and other features
- The KnowledgeSmart integration is a good example of this.
- Embedding Assessment and other features
This is a flow diagram for a better understanding of the logic for API calls when logging into the KnowledgeSmart admin site, user pages, taking a Skills assessment, and viewing results.
Below is a summary overview of the different types of actions the current KnowledgeSmart API functionality offers. Please scroll to the bottom of this article for a link to our Swagger site for the actual API calls and further guidance.
- Get basic account information.
- Specify UI settings.
- Specify self-invite settings.
- Request login token – SSO authentication for logging into the platform.
- Get a list of users (account ID, user ID, email address, data fields).
- Get users by email address from the HR system or LMS, for example.
- Add a user to the current account and send them an email with login information.
- Update user information – user name, email address, and additional data fields.
- Check whether the user has accepted the terms and conditions.
- Get assessment results for a user
- Assessment date.
- Assessment ID.
- User status.
- Get results for a user – detailed
- User status.
- IsExam? (was the result from an exam with score bandings).
- Score (and ability to not show score).
- Test date.
- Last active Time.
- Total elapsed Time.
- Test name.
- Result ID.
- Data fields.
- Training Tags.
- Test ID.
- Module ID.
- Module Names.
- Get a list of invitation email templates for this account.
- Resend invitations from a list of invite ID's.
- Get all assessments for the current account.
- Get assessments for the currently logged-on account.
- Assessment progress.
- Get the status of a single assessment.
- Extend an expiry date.
- Remove an expiry date.
- Get all assessments for the current account that are started but not completed (in Progress).
- Gets all the assessments for the current account that are completed.
- Gets all the assessments for the current account that are not started.
- Get all assigned assessments for a user for the current account that are not started.
- Get all assessments for a user for the current account that is completed.
- Get training gaps for a user for an individual assessment (list this data inside their HR or LMS profile).
- Get training gaps for a user for an assessment for a user (could be from many assessments).
- Assign an assessment for a user but no email is sent.
- Create an assessment invite and sends an email with a link to the test.
- Delete a specific invite.
Here is a list of the 10 most used API calls:
List assessments for logged in account:
Invite user to an assessment (replace the query string elements as required):
List users for account:
Search users by name (change the name value to a name you want to search):
Search users by ID (change the userid value to an ID you know):
List results for account:
List results for a user (change the userid value to an ID you know):
Show all results for a particular test ID:
It will return the results for a given test ID for the logged-in account.
Add a new user:
Simply substitute the email/firstname/lastname to the user you would like to add. If a user
already exists with that email address, then that user is added to the account.
Get answers for a result:
Pass in the resultID you would like to see the answers for. NB, you would probably use the
existing methods GetAllResults or GetResultsForUser first to get the list of results and their
resultIDs, which you could then pass in
Click the link below for a full list of currently available API calls: