Learning Impact APIs

Introduction

Learning Impact

The Learning Impact app allows Superadmins and Power Users to enable ready-to-use questionnaires for individual courses in your platform. They are sent to learners via email or in-platform notifications when they complete a course, in order to measure the learning impact of the training. Questionnaires are diversified according to the course or session type: E-Learning, ILT and VILT sessions. The questionnaire results are then turned into easy-to-read reports that are accessible directly in the platform.

APIs

An API (Application Programming Interface) is software that sends or receives information back and forth between a website or app and a user via a process of an API call, which is simply the term used to describe a connection being made to a specific address and certain data being exchanged. As a rule API calls use standard HTTPS calls to make their connections using pre-set credentials that are transmitted securely via encrypted connections. API calls can be requests for data or data updates or even instructions to perform a specific task. 

While APIs can be run manually, their true power is unlocked when used in an automated manner, by one application exchanging data with another. This allows you to extend the functionality of the platform containing the API system by using other, possibly unrelated, systems to automate tasks or integrate with the platform.

All Docebo Learning Impact endpoints are documented individually in detail in the Docebo Learning Impact API Documentation (opens in a new tab).

Prerequisites

In order to be able to access Docebo Learning Impact via API you need to use a private key, supplied by Docebo. If you do not have the necessary key to proceed, please contact your Docebo Account Manager or reach out to the Help Desk via the Help Center.

Accessing Docebo Learning Impact via API

The Docebo Learning Impact API uses JWT Bearer Grant Type with the OAuth2.0 protocol used for authentication purposes. The JWT Bearer grant type is used when the client wants to receive access tokens without transmitting sensitive information such as the client secret. This can also be used with trusted clients to gain access to user resources without user authorization.

Data is exchanged by the use of JSON. This format is an industry standard, used for passing data and be implemented using a large variety of structure types. For our purposes we only need a simple structure in our JSON statements:

{ 
    “Name” : “Value”
}

Authentication

In order to authenticate with the API platform, an access token must be first generated. This allows for seamless communication between the sender and the recipient and grants all the necessary permissions to perform the desired actions via API calls.

The steps taken to generate an access token are:

• Build a JWT token
  This step creates the user data in JSON format
• Encrypting the JWT token
  This converts the data to encrypted, non human readable, code for security purposes
• Generating an access token
  This creates the access token needed for API authentication

Build a JWT Token

You can generate a JWT token with the method of your choice. There are many resources, such as samples as well as libraries for various different programming languages, available on the jwt.io (opens in a new tab) web site.

To create a JSON WEB Token that can be used to authenticate within Docebo, you must set the signature algorithm and use your Docebo supplied private key to encrypt your payload.

For the purposes of providing an interface that is easy to follow along, we will be using the jwt.io (opens in a new tab) website to build and encrypt the JWT token.

The first step is to select the type of algorithm we will use to encrypt the data.There are many different algorithms that are capable of performing this task, at Docebo we use the RS256 algorithm.

In the Algorithm drop down box at the top of the screen, select RS256 as the algorithm of choice:

The Encoded text box is the output box, this is where you will eventually be able to copy your encrypted token once all the relevant data has been entered into the text boxes on the right hand side of the screen.

The Header text box is generated (and updated itself already when you changed your encryption algorithm) and can be left alone.

The Payload text box contains the data that is necessary to create your encrypted token, here you will need to remove the default contents and add the following information, an example of the format will follow the description of the fields:

 Here is an JSON formatted payload showing example data:

{
    "aud": "https://accounts.emea2.learningimpact.docebo.com/",
    "iss": "mydliplatform.com",
    "sub": "myAdmin",
    "iat": 1516239022,
    "exp": 1627028854,
    "scope": "registration",
    "rights": []
}

Place this information into the Payload field of the jwt.io website.

You have now successfully built the JWT token and can move on to the next step.

Encrypting the JWT Token

Encryption is a way of altering the data so that it cannot be read by someone who does not have the necessary key to unlock it. This process involves two sets of keys, a public key and a private key. Typically the sender and recipient of the encrypted message both have their own sets of private and public keys. The sender encrypts the message using their own private key and the recipient’s public key. This message can then only be decrypted by using the recipient’s private key and the sender’s public key on the other end. This method ensures that nobody, except for the intended recipient is able to view the data contained in the sent message.

Next you need to add your supplied private key in the private key field of the Verify Signature box. You may leave the Public Key or Certificate text box blank.

Once you have pasted your key you can copy the encrypted token from the Encoded text box and paste it into a text editor for safekeeping. 

Access Token Generation

To generate the access token we will use a tool called Postman, a tool used to communicate with the API and to send the request.

First you need to import a cURL statement in Postman. Copy the code shown here and paste it into an import window under the Raw Text tab in Postman.

curl --request POST --url https://accounts.emea2.learningimpact.docebo.com/token --header 'content-type: 
application/x-www-form-urlencoded' --cookie PHPSESSID=ks8l9pfsbru6abh564e05m7rif 
--data grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer 
--data assertion=myencryptedJWT --data scope=registration

The cURL statement sends a POST request to the server. POST requests are essentially the same as an HTML form you see in a web page, they send data to a remote server and await a response. There are other types of requests that can be sent as well, such as GET which exposes the variables you wish to send in the URL of the request itself and is typically used for simpler requests, for example, retrieving a record based solely on a record ID being sent. DELETE which is used for deleting values on the server end, PUT which can be used for adding a record to the server or PATCH which, as the name implies, updates a record or data. The type of request you use matters as the behavior of the server can be very different depending on whether you send a GET or DELETE request containing the same data to the same URL.

Alternatively you may also import a pre-configured collection provided by Docebo into Postman by by clicking on Import, followed by Link and then pasting

https://www.getpostman.com/collections/89a9855c7ad885632245 

into the text box.

After the import has completed you will see the following information in Postman:

As you can see the method used is POST, the URL the request is sent to is https://accounts.emea2.learningimpact.docebo.com/token. That would be the API “endpoint” (a name for the URL of a specific API command, which is what is accessed to “call” the API). 

For the purposes of creating the access token, edit the values in the table and replace {{assertion}} by the encoded JWT token generated in the previous step. Then click on the Send button or if you use the collection and the environment shared by Docebo, the assertion will be automatically populated.

The response from the server will include your access token:

The full server response includes the following variables:

• Access token
  The token to be used for authentication
• Expires in
  The number of days the token is valid for, starting from the day of creation
• Token type
  The type of the token. In the previous picture we used JWT in an assertion similar to how we use the access token in bearer which can be found in the example API Call.