Praesidium APIs
This book contains the official documentation for all APIs which Praesidium makes available to its clients
Event Publishing Specification
This document provides the build specification to clients who wish to receive learning event notifications programmatically.
Changelog
2023-03-15 |
Added several refX fields to event_specific_detail |
2023-01-20 |
Clarified meaning of UUID in eventContext Corrected typo in learning_path_completed sample payload |
2022-12-20 |
Added LEARNING_PATH_COMPLETED event type |
2022-12-13 |
Corrected payload property names from camel case to snake case |
2022-01-12 | Added first_name and last_name fields to COURSE_COMPLETED payload in event_specific_detail to aid with the resolution of matching errors |
Overview
In general, a client will reach out to Praesidium to identify relevant events and an endpoint to which to publish them in near real-time. Authentication credentials (to be used with HTTP Basic Authentication) may be provided securely to Praesidium as well. Praesidium will then set up the event subscription for the client in question. From the time of setup onward, any relevant events that happen will be communicated in near real-time to the endpoint specified by the client.
Event Payload
The event payload will take the form of a JSON Object as follows:
{
"version": <STRING>,
"event_type": <STRING>,
"event_timestamp": <STRING>,
"event_context": <JSON>,
"event_specific_detail": <JSON>
}
where
version - the version string (value: "1.0")
event_type - what kind of event is being reported. Event type will determine the structure of event_context (see below)
event_timestamp - a UTC timestamp in ISO format (i.e. YYYY-MM-DD HH24:MM:SS)
event_context - a JSON object with a specific structure depending upon event_type
event_specific_detail - a JSON object with additional contextual information that may differ depending on event_type
Accepted Return Values
In keeping with general RESTful principles, HTTP Status codes should be used. A return value of 400 should be used if the event payload violates the specification above or is otherwise malformed. A return value of 200, 201 or 202 should be returned to indicate that the event record was successfully received.
Event Types
COURSE_COMPLETED
The event context structure will consist of 2 fields inside the JSON object
- uuid - This field will contain the UUID of the user as returned by user creation via the REST API
- user – This field will contain the email address needed to identify the user who completed the course
- course – This field will contain a JSON object with 2 fields:
- id: the course sku for the course completed
- name: the course name for the course completed
The event_specific_detail field now contains an object user_detail with the following fields:
- first_name
- last_name
- clientExternalId - this field will hold the value from the Academy user record that the client has provided uniquely identifying this user in their system. (Note: this field may be null if the client is not using this feature.
- ref3 - this corresponds to the ref3 element in the Academy user record
- ref4 - this corresponds to the ref4 element in the Academy user record
- ref5 - this corresponds to the ref5 element in the Academy user record
- ref7 - this corresponds to the ref7 element in the Academy user record
- ref8 - this corresponds to the ref8 element in the Academy user record
- ref9 - this corresponds to the ref9 element in the Academy user record
Example Payload
{
"version": "1.0",
"event_type": "COURSE_COMPLETED",
"event_timestamp": "2018-03-01 17:45:37",
"event_context": {
"uuid": "aaaaaaaa-bbbb-cccc-dddd-ffffffffffff",
"user": "email@gmail.com",
"course": {
"id": "CON20938ES",
"name": "Duty to Report: Mandated Reporter"
}
},
"event_specific_detail": {
"user_detail": {
"first_name": "Tester",
"last_name": "Testerman",
"clientExternalId": "1234569",
"ref3": "arbitrary text",
"ref4": "arbitrary text2",
"ref5": "arbitrary text3",
"ref7": "arbitrary text4",
"ref8": "arbitrary text5",
"ref9": "arbitrary text6",
}
}
}
LEARNING_PATH_COMPLETED
The event context structure will consist of 2 fields inside the JSON object
- uuid - This field will contain the UUID of the user as returned by user creation via the REST API
- user – This field will contain the email address needed to identify the user who completed the course
- learning_path – This field will contain a JSON object with 2 fields:
- id: the learning path sku for the learning path completed
- name: the learning path name for the learning path completed
The event_specific_detail field now contains an object user_detail with the following fields:
- first_name
- last_name
- clientExternalId - this field will hold the value from the Academy user record that the client has provided uniquely identifying this user in their system. (Note: this field may be null if the client is not using this feature.
- ref3 - this corresponds to the ref3 element in the Academy user record
- ref4 - this corresponds to the ref4 element in the Academy user record
- ref5 - this corresponds to the ref5 element in the Academy user record
- ref7 - this corresponds to the ref7 element in the Academy user record
- ref8 - this corresponds to the ref8 element in the Academy user record
- ref9 - this corresponds to the ref9 element in the Academy user record
Example Payload
{
"version": "1.0",
"event_type": "LEARNING_PATH_COMPLETED",
"event_timestamp": "2018-03-01 17:45:37",
"event_context": {
"uuid": "aaaaaaaa-bbbb-cccc-dddd-ffffffffffff",
"user": "email@gmail.com",
"learning_path": {
"id": "CONLP10023EN",
"name": "Duty to Report: Mandated Reporter"
}
},
"event_specific_detail": {
"user_detail": {
"first_name": "Tester",
"last_name": "Testerman",
"clientExternalId": "1234569",
"ref3": "arbitrary text",
"ref4": "arbitrary text2",
"ref5": "arbitrary text3",
"ref7": "arbitrary text4",
"ref8": "arbitrary text5",
"ref9": "arbitrary text6",
}
}
}
Testing
COURSE_COMPLETED Test Endpoint
This endpoint will allow a client to manually trigger the mechanism which sends course completion events back to client systems. The client can specify an endpoint to which to send the test event payload. The client will send a payload to the Praesidium endpoint and a success response will be sent to the endpoint that the client specified.
Endpoint: https://test.praesidiumacademy.com/portal/event_pub_webhooks/client_course_action
Method: POST
Sample Payload (note the "T" embedded in the "date" field format)
{
"client_id": "35F5C5A985D111EB857A0A3ECA36592D",
"user_guid": "584adf35-85d1-11eb-857a-0a3eca36592d",
"email": "lcarl@notreallythere.com",
"location_guid": "5f383262-85d1-11eb-857a-0a3eca36592d",
"courseSku": "TCCE1001",
"date": "2021-03-11T12:01:03",
"url": "https://test.client.eventpublication/endpoint"
}
Note that the url parameter is optional. When present, the current client event publishing endpoint will be changed to the url value in the payload and will be the endpoint used until it is changed again.
Sample Response (HTTP 200)
{
"message": "success"
}
User Management REST API
This document details the RESTful API methods available to manage users for Praesidium clients.
Changelog
2024-08-18 |
|
2023-10-30 |
|
2023-01-18 |
|
2022-10-18 |
|
2021-05-18 |
|
2021-02-26 |
|
Overview
Methods are available to perform the following operations:
- Retrieve a User Record (GET)
- Create a new User Record (POST)
- Update a User Record (PUT)
- Deactivate a user record (PUT) - remove system access
- Add content to a user record (PUT)
Unless otherwise specified, all services require the JWT token to be passed in the Authorization: Bearer header
In addition to all other potential error messages listed below, any endpoint may return HTTP 429 Too Many Requests. If this code is returned, a Retry-After header will be attached to the message to indicate how long to wait before retrying the request.
Any duplicate requests to change data (e.g. Create, Update, Deactivate, Enroll) within 30 seconds will be ignored.
Authentication
JWT expiration is 900 seconds (15 minutes)
URL | /portal/authenticate/login_api |
Method |
POST |
Data Format |
The only valid scope value is: "prae.client.api.user" |
Success Response |
HTTP Status Code: 200
The Refresh token can be used to generate a new access token (if it has not expired) by passing it in the Authorization: Bearer header and using an HTTP GET to retrieve /portal/session/refresh_jwt |
Failure Response |
Authentication Error HTTP Status Code: 401 Authorization Required
Input Validation Error HTTP Status Code: 400 Bad Request
Invalid Scope Error HTTP Status Code: 400 Bad Request
|
Example |
|
Resource: User
Structure of the User Object
All data fields in the user object will fall into one of five categories:
- Principal – this category is for personal information that is primarily used to identify the user
- System – this category is for system information, such as roles, status (active or inactive)
- Person – this category is for other personal information that is not used to identify the user
- Context – this category is for information describing the contexts that apply to the user
- Attributes – this category is for information describing the user that can be used to determine which course assignments are applied, and for reporting purposes
So, in general a user object (for the purpose of this API is defined by the following format:
{
"principal": {
"UUID": "<string>",
"first_name": "<string>",
"last_name": "<string>",
"email": "<email>",
"client_external_id": "<string>"
},
"system": {
"status": "<(active | inactive)>",
"role": "<role-value>"
},
"person": {
},
"context": {
"client": "<UUID>",
"locations": [
"<UUID1>",
"<UUID2>",
...,
"<UUIDN>"
],
"content": [
{
"uuid": "<UUID>",
"type": "<content_type-value>"
},
...
]
},
"attributes": {
"program_type": "<program_type-value>",
"position": "<position-value>"
}
}
Currently, the only valid content_type-values are "course" and "learning path"
The only valid role-values are:
- Learner: The user in question can only take courses, and has no administrative access
- Administrator: The user in question can edit user info for non-administrative user
- Administrator - View Only: The user in question has administrative access, but cannot edit any information
General Notes about the fields included in the user object relevant to individual REST operations
When using a POST to create a user, the UUID field at the top level is optional.
The "content" object under the "context" object is optional when passing a user object to POST for creation or PUT for general update
In addition, the "content" object will never be specified in a return value from an API call for performance reasons
The UUIDs under "client", "locations" and "content" will be provided by Praesidium (csv file will contain UUID, name for client and locations, and will additionally contain content_type and SKU for courses/learning paths)
Retrieve a User Record
URL | /portal/lms_api/v2/user/{UUID} |
Method |
GET |
Path Parameters |
Required UUID - UUID for the desired user |
Success Response |
HTTP Status Code: 200 User object (structure as described above) |
Failure Response |
Input Validation Error HTTP Status Code: 400 Bad Request
Not Found Error HTTP Status Code: 404 Not Found
Internal Server Error HTTP Status Code: 500 Internal Server Error
status - integer HTTP status message - Human readable error messages, separated by new lines |
Example |
|
Create a New User
Upon creation, the user will be automatically enrolled in any content included in the payload
Email addresses must be unique across all Academy.
If an attempt is made to create a user with an email that already exists in Academy, the technicalMessage property of the HTTP 400 error will now contain the id of the user with the existing email IF that user falls under the requesting client's hierarchy.
URL | /portal/lms_api/v2/user |
Method |
POST |
Data Parameters |
Required User object (structured as above). Any value in the UUID field will be ignored. |
Success Response |
HTTP Status Code: 201 User object (structure as described above). The UUID field will contain the UUID of the newly created user |
Failure Response |
Input Validation Error HTTP Status Code: 400 Bad Request
Internal Server Error HTTP Status Code: 500 Internal Server Error
status - integer HTTP status message - Human readable error messages, separated by new lines |
Example |
|
Update an Existing User
Note: upon completion of other updates, the user will be automatically enrolled in any content included in the payload
URL | /portal/lms_api/v2/user/{UUID} |
Method |
PUT |
Path Parameters |
Required UUID UUID for the user to be updated |
Data Parameters |
Required User object (structured as above). |
Success Response |
HTTP Status Code: 200 User object (structure as described above). |
Failure Response |
Authorization Error HTTP Status Code: 403
Input Validation Error HTTP Status Code: 400 Bad Request
Not Found Error HTTP Status Code: 404 Not Found
Internal Server Error HTTP Status Code: 500 Internal Server Error
status - integer HTTP status message - Human readable error messages, separated by new lines |
Example |
|
Deactivate an Existing User (Remove system access)
URL | /portal/lms_api/v2/user/{UUID}/deactivate |
Method |
PUT |
Path Parameters |
Required UUID - UUID for the desired user |
Success Response |
HTTP Status Code: 200 User object (structure as described above) |
Failure Response |
Authorization Error HTTP Status Code: 403
Input Validation Error HTTP Status Code: 400 Bad Request
Not Found Error HTTP Status Code: 404 Not Found
Internal Server Error HTTP Status Code: 500 Internal Server Error
status - integer HTTP status message - Human readable error messages, separated by new lines |
Example |
|
Add Content to an Existing User
URL | /portal/lms_api/v2/user/{UUID}/enrollContent |
Method |
PUT |
Path Parameters |
Required UUID UUID for the user to be updated |
Data Parameters |
Required Content Listing (structured as below).
uuid - course UUID (Praesidium provided) |
Success Response |
HTTP Status Code: 200 User object (structure as described above). |
Failure Response |
Authorization Error HTTP Status Code: 403
Input Validation Error HTTP Status Code: 400 Bad Request
Not Found Error HTTP Status Code: 404 Not Found
Internal Server Error HTTP Status Code: 500 Internal Server Error
status - integer HTTP status message - Human readable error messages, separated by new lines |
Example |
|
Remove Content from an Existing User
WARNING: Removing a Learning Path from a user will NOT remove the corresponding courses
URL | /portal/lms_api/v2/user/{UUID}/removeContent |
Method |
PUT |
Path Parameters |
Required UUID UUID for the user to be updated |
Data Parameters |
Required Content Listing (structured as below).
uuid - course UUID (Praesidium provided) |
Success Response |
HTTP Status Code: 200 User object (structure as described above). |
Failure Response |
Authorization Error HTTP Status Code: 403
Input Validation Error HTTP Status Code: 400 Bad Request
Not Found Error HTTP Status Code: 404 Not Found
Internal Server Error HTTP Status Code: 500 Internal Server Error
status - integer HTTP status message - Human readable error messages, separated by new lines |
Example |
|
Re-Enroll Content in an Existing User
Note: User’s content that is re-enrolled will be set to a not-started status in Academy. Any prior completion certificates will be unchanged.
WARNING: Re-Enrolling a user in a Learning Path will NOT re-enroll that user in the corresponding courses
URL | /portal/lms_api/v2/user/{UUID}/reEnrollContent |
Method |
PUT |
Path Parameters |
Required UUID UUID for the user to be updated |
Data Parameters |
Required Content Listing (structured as below).
uuid - course UUID (Praesidium provided) |
Success Response |
HTTP Status Code: 200 User object (structure as described above). |
Failure Response |
Authorization Error HTTP Status Code: 403
Input Validation Error HTTP Status Code: 400 Bad Request
Not Found Error HTTP Status Code: 404 Not Found
Internal Server Error HTTP Status Code: 500 Internal Server Error
status - integer HTTP status message - Human readable error messages, separated by new lines |
Example |
|