Docebo Learning Impact APIs – Docebo Help & Support

Introduction

Docebo Learning Impact

The Docebo 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.

For additional information, including how to configure Docebo Learning Impact, please see Activating and Managing the Docebo Learning Impact App

Activating Docebo Learning Impact

Activate the Docebo Learning Impact app as described in the Managing Apps & Features article of the Knowledge Base. The app is listed in the Docebo Additional Features tab.

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.

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 creating 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 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 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:

Field Name	Value / Description
`aud`	This field contains the URL of the production authentication server you wish to access. For EMEA, use `https://accounts.emea1.learningimpact.docebo.com` If you are still on formetris.com, use `https://accounts.formetris.com` For USA, use `https://accounts.us.learningimpact.docebo.com`
`iss`	This value is your Docebo client domain. For Docebo LMS clients this can be either `[yourlms].docebosaas.com`, or, if you have a custom domain you may use that domain name. If you are not a Docebo LMS client please use `[yourlms].docebosaas-standalone.com`. For a sandbox environment use `yourSandboxDomain.docebosaas-sandbox.com`
`sub`	This field refers to the username, you may use a string value here.
`iat`	The current moment's timestamp. You can use https://www.epochconverter.com/ in order to generate a timestamp from a human readable date.
`exp`	The timestamp of the token’s expiration date. This value must be in the future. You can use https://www.epochconverter.com/ in order to generate a timestamp from a human readable date.
`scope`	For registration endpoints use "registration" here. For reporting endpoints, for example: /reporting/attendance or /reporting/evaluations, use "reporting" here.
`rights`	Use “[]” do not modify this value.

Here is an JSON formatted payload showing example data:

{
    "aud": "https://accounts.formetris.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.formetris.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.formetris.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.

Classic API Flow using Example Calls

Introduction

We will now walk through the typical flow of the API using example calls. In this scenario we will perform the following actions:

Register a course using the Courses endpoint
Register a session in the course using the Sessions endpoint
Register a learner in a session using the Learners endpoint
Subscribe a learner for evaluation after they have completed the session

Prerequisites

Please note that the examples below are not compatible with Docebo Learn customers. For Docebo Learn, DLI is already tightly integrated with the system and these API calls would be redundant.

The access token generated previously can be used for service calls. As shown in the following examples.

In order to use these examples you can use Postman. First click on the Authorization tab and then enter your token in the field provided. Then click the Save button in the top right corner of the screen.

This will ensure that your API calls will send the appropriate credentials with every endpoint you access.

In order to enter the appropriate payload, click on the Body tab and then click on the Raw radio button. This will change your input field to a plain text editor where you can input the payload you wish to send. Don’t forget to change the URL next to the POST drop down menu, this is where you will enter your endpoint URL.

Please note, email address fields in the API payloads do not support unicode characters. They must follow the standard of visible US-ASCII characters. For verification you can use the following RegEx code:
^(([^<>()\[\]\.,;:\s@\"]+(\.[^<>()\[\]\.,;:\s@\"]+)*)|(\".+\"))@(([^<>()[\]\.,;:\s@\"]+\.)+[^<>()[\]\.,;:\s@\"]{2,})

The Courses Endpoint

In this example we are going to use an API call to create a new course.

You will need to enter the following values to send which will result in creating a new course.

title: Your course title.
types: Acceptable values for this variable are: “classroom”, “webinar” or “elearning”.
metadata:

clientDomain: Your Docebo client domain. If you are not a Docebo Learn client please use [yourname].docebosaas-standalone.com. For sandbox environments use [yourSandboxDomain].docebosaas-sandbox.com.
courseID: Unique identifier of the course. For example, your courseID.
courseAdditionalFields

Here you can add additional fields, for example "TrainingCategory", to add more specific attributes to the course.
If a new course additional field is detected in one of these calls, it will automatically created on your DLI account

Here is the code you would use in the Raw editor:

{
    “courses”: [
    {
        “title”: “Kitesurf Workouts”,
        “types”: [
            “classroom”
        ],
        “metadata”: {
            “clientDomain”: “acme.docebosaas.com”,
            “courseID”: “I am CourseID”
            "courseAdditionalFields": [
                {
                 "fieldName": "myCustomFieldName",
                 "fieldValue": "myCustomValue"
                }
            ]
        }
    }
]
}

In the Raw editor it would look like this:

After obtaining a successful response, you will be able to find the course in your DLI environment.

You can find more information on this endpoint in the Docebo Learning Impact API documentation.

The Sessions Endpoint

In this example we are going to use an API call to create a new session in a course

You will need to, at a minimum, enter the following values to send which will result in creating a new session:

sessions

module

metadata:

clientDomain: The domain in which the course is registered.
courseID: Unique identifier of the course. If you were creating a session in the course you created in the previous step of these examples, you would use that course ID.

session

metadata:

sessionId: The session ID in your LMS or Training Management System
Session Additional Fields (if a new session additional field is detected in one of these calls, it will be automatically created in your DLI account)

trainers (not mandatory)

metadata:

userID: The UserID of the trainer, if possible. The email address of the trainer can also be used here.

Here is an example of the code you would use in the Raw editor:

{
  "sessions": [
    {
      "module": {
        "metadata": {
          "clientDomain": "acme.docebosaas-sandbox.com",
          "courseId": "myCourseId123"
        }
      },
      "session": {
        "metadata": {
          "sessionId": "mySessionId123",
          "sessionAdditionalFields": [
            {
              "fieldName": "myCustomFieldName",
              "fieldValue": "myCustomValue"
            }
          ]
        }
      },
      "startDate": "2021-06-15",
      "endDate": "2021-06-15",
      "locale": "en",
      "country": "us",
      "trainers": [
        {
          "firstname": "John",
          "lastname": "Trainer",
          "locale": "en",
          "email": "john.trainer@mail.com",
          "metadata": {
            "userId": "jtrainerId"
          }
        }
      ],
      "reportRecipients": [
        {
          "firstname": "John",
          "lastname": "johnRecipient",
          "locale": "en",
          "email": "john.recipient@mail.com",
          "metadata": {
            "userId": "jReportRecipId"
          }
        }
      ],
      "locations": [
        {
          "locationName": "Paris"
        }
      ]
    }
  ]
}

The Learners Endpoint

In this example we are going to use an API call to enroll a user in a session.

You will need to, at a minimum, enter the following values to send which will result in the user(s) being enrolled:

learners

module

metadata

clientDomain: example: acme.docebosaas-sandbox.com
courseId: The courseId value you set in the Courses endpoint

firstname: The first name of the user
lastname: The last name of the user
locale: The language of the learner which will be used for all emails and questionnaires, for example: en
email: The email address of the user
metadata

userId: The user ID of the user.

manager

metadata

userId: The user ID of the user’s manager.

session

metadata

sessionId: The session ID value you set in the session endpoint

Here is an example of the code you would use in the Raw editor:

{
  "learners": [
    {
      "module": {
        "metadata": {
          "clientDomain": "acme.docebosaas-sandbox.com",
          "courseId": "myCourseId123"
        }
      },
      "firstname": "John",
      "lastname": "Learner",
      "locale": "en",
      "email": "john.learner@mail.com",
      "metadata": {
        "userId": "jLearnerId"
      },
      "manager": {
        "firstname": "John",
        "lastname": "Manager",
        "locale": "en",
        "email": "john.manager@mail.com",
        "metadata": {
          "userId": "jmanagerId"
        }
      },
      "session": {
        "metadata": {
          "sessionId": "mySessionId123"
        }
      }
    }
  ]
}

The Subscription Endpoint

In this example we’re going to use an API call to subscribe a user for the Learning Impact evaluation. This API call would be used once the learner, defined in the previous example, has completed the session, defined in the second example, they were enrolled in.

You will need to, at a minimum, enter the following values to send which will result in the user(s) being subscribed for evaluation:

learners

module

metadata

clientDomain: example: acme.docebosaas-sandbox.com
courseId: The courseId value you set in the Courses endpoint

trainee

metadata

userId: The user ID of the user.
branches: The branches the user is a member of. Usually this is an empty array but must be supplied even if there is no data to populate it with.

userAdditionalFields

Here you can add additional fields, for example "Country" or "Division", to add more specific attributes to the learner.
If a new User Additional Field is detected, it will be automatically created in your DLI account

session

metadata

sessionId: The session ID value you set in the session endpoint.

Here is an example of the code you would use in the Raw editor:

{
  "learners": [
    {
      "module": {
        "metadata": {
          "clientDomain": "acme.docebosaas-sandbox.com",
          "courseId": "myCourseId123"
        }
      },
      "trainee": {
        "metadata": {
          "userId": "jLearnerId",
          "branches": [
            "branchedId"
          ],
          "userAdditionalFields": [
            {
              "fieldName": "myCustomFieldName",
              "fieldValue": "myCustomFieldValue"
            }
          ]
        }
      },
      "session": {
        "metadata": {
          "sessionId": "mySessionId123"
        }
      }
    }
  ]
}

Docebo Help

How can we help?

Introduction