Инструкция по интеграции с цифровой платформой УНТИ 2035
Цифровой след. Общие сведения
Цифровой след (ЦС) – это данные об образовательной, профессиональной или иной деятельности человека, представленные в электронной форме.
Цифровой след используется для анализа развития человека с целью подтверждения получения им нового опыта деятельности, подготовки рекомендаций по следующему шагу развития, накопления данных о траекториях развития, для совершенствования работы системы рекомендаций.
Формат цифрового следа
Цифровой след передается в формате xAPI (https://xapi.com/).
Структуры данных и протоколы для приема цифрового следа: Структуры данных и протоколы для приема цифрового следа.
Состав цифрового следа на проекте в части данных о пользователе и данных об обучении
Данные о Получателях поддержки, передаваемые Провайдером, включают в себя следующие сведения:
Информация о Получателях поддержки:
1. идентификатор Получателя поддержки на платформе, где размещена программа обучения;
2. Unti-id;
3. ФИО.
Цифровой след Получателей поддержки, прошедших входную / итоговую диагностику :
1. информация о Получателе поддержки;
2. идентификатор программы;
3. результаты входной / итоговой диагностики Получателей поддержки с указанием следующих данных:
3.1. оценка результата в соответствии с критериями;
3.2. соответствие / несоответствие результата входной диагностики / тестирования требуемому уровню для вхождения в программу.
Оценка результатов деятельности Получателей поддержки в рамках модуля с указанием следующих данных:
1. информация о Получателе поддержки;
2. идентификатор программы;
3. идентификатор модуля, в рамках которого осуществлялась деятельность;
4. постановка задачи;
5. предполагаемая форма результата деятельности (презентация, текстовый документ, программный код и т.п.);
6. подход к оценке результата и критерии оценки результата деятельности;
7. шкала оценивания;
8. оценка результата;
9. успешность прохождения итоговой деятельности (успешно / неуспешно);
10. файл, содержащий фактический результат промежуточной деятельности (файл должен прилагаться и быть доступен для ознакомления / просмотра);
11. тип деятельности (групповая / индивидуальная).
Оценка результатов аттестации в рамках модуля или программы (в случае итоговой аттестации) (тест / экзамен / решение кейсов и т.д.) с указанием для каждой попытки прохождения аттестации следующих данных:
1. информация о Получателе поддержки (в соответствии с пунктом 4);
2. идентификатор программы;
3. идентификатор модуля, в рамках которого осуществлялась аттестация;
4. название модуля, в рамках которого осуществлялась аттестация;
5. идентификатор или название аттестации (на стороне образовательной платформы организации);
6. минимальная возможная оценка / максимальная возможная оценка (заполняется для тестов);
7. пороговое значение для успешной аттестации;
8. тип аттестации (тест, решение кейсов и т.д.);
9. оценка промежуточной аттестации;
10. максимальное число попыток прохождения (заполняется для тестов);
11. порядковый номер попытки прохождения (заполняется для тестов);
12. успешность прохождения аттестации (успешно/не успешно).
Оценка результатов итоговой деятельности Получателей поддержки (в случае проектной деятельности) с указанием следующих данных:
1. информация о Получателе поддержки (в соответствии с пунктом 4);
2. идентификатор программы;
3. постановка задачи;
4. предполагаемая форма результата деятельности (презентация, текстовый документ, программный код и т.д.);
5. перечень инструментов, необходимых для реализации деятельности (power point, jupyter notebook и т.д.);
6. подход к оценке результата и критерии оценки результата деятельности;
7. шкала оценивания;
8. тип деятельности (индивидуальный/групповой);
9. оценка результата;
10. успешность прохождения итоговой деятельности (успешно/не успешно);
11. файл (или файлы), содержащий фактический результат итоговой деятельности (файл должен прилагаться и быть доступен для ознакомления / просмотра).
Данные о просмотре видео-контента программы, при наличии (информация дается по каждому видеоролику, который есть в программе):
1. информация о Получателе поддержки (в соответствии с пунктом 4);
2. идентификатор программы;
3. идентификатор модуля, к которому относится видеоролик;
4. id видеоролика или его название (на стороне образовательной платформы организации);
5. номер видео в уроке;
6. номер урока в модуле;
7. название урока;
8. продолжительность видеоролика в минутах;
9. дата и время начало просмотра видеоролика;
10. % просмотра видеоролика;
11. просмотр видео «played», опционально;
12. досмотрел видео до конца «complete», опционально;
13. приостановил просмотр видео «paused», опционально;
14. изменил скорость воспроизведения видео «change-playbackspeed», опционально;
15. прервал просмотр видео «skipped», опционально;
16. перемотал видео к определенному времени «rewind», опционально.
Интерфейсы Платформы Университет.2035 для сбора ЦС
На платформе 2035 цифровой след хранится в LRS - специализированном хранилище данных о цифровом следе пользователя. LRS предоставляет API для загрузки цифрового следа.
Возможны два варианта загрузки цифрового следа в LRS:
- Провайдер контента может передать подготовленный файл формата xAPI в систему Университета.2035 вручную через POST запрос в LRS.
- В случае если система обучения (LMS) Провайдера контента имеет возможность установки готовых плагинов по передаче данных в формате xAPI, то цифровой след может передаваться с использованием плагина.
Обратите внимание, что плагины могут не поддерживать все необходимые требования к составу и передаче цифрового следа.
Для синхронизации id студента, по которому ОО будет передавать на платформу цифровой след, необходимо также реализовать интеграцию с системой аутентификации и авторизации (SSO) Платформы Университета 2035.
С более подробной информацией можно ознакомиться по ссылке.
Интеграция с системой аутентификации и авторизации (SSO)
Этапы интеграции с Университетом 2035
Кратко этапы интеграции с SSO с точки зрения ОО выглядят так:
- запросить доступ к API SSO на тестовом контуре и дождаться ответа с секретным ключом;
- реализовать логику обращения к нашему API;
- добавить на сайт кнопку авторизации (с учетом гайда по использованию элементов дизайна 2035);
- протестировать взаимодействие с нашим API на тестовом контуре;
- запросить доступ к API SSO на продакшен контуре и дождаться ответа с секретным ключом.
Для получения консультации по интеграции необходимо с корпоративного адреса электронной почты написать письмо на apps@2035.university с сутью вопроса, приложив по возможности скриншоты/скринкасты до и после описываемого события, url и параметры запросов.
Запросы доступа к API SSO
Запросы на тестовый и продуктовый контур имеют одинаковый формат.
Необходимо с корпоративного адреса электронной почты отправить письмо на apps@2035.university следующего содержания:
- Тема письма: Подключение к API SSO Полное наименование организации. Тестовый/Продуктовый контур;
- Текст письма:
- Наименование организации: Полное наименование организации;
- Проект: Проект;
- Контур: тестовый/продуктовый;
- Домен/ссылка сервиса (url) – адрес, откуда будут отправляться запросы. Если ссылок несколько, то нужно будет создавать несколько OAuth клиентов;
- Домен/ссылка перенаправления (redirect_uri) – адрес, на который будет перенаправлен пользователь после авторизации в SSO, к которому также будет добавлен get параметр code; Обратите внимание: redirect_uri, который вы будете указывать в запросе, должен точно совпадать с прописанным в настройках клиента (например, если в клиенте https://staging.experts.work/, а в запросе http://staging.experts.work/ или https://staging.experts.work или https://staging.experts.work/auth/callback/, вы получите ошибку)!
- Идентификатор приложения клиента (client_id) – формируется клиентом самостоятельно и проверяется Университетом 2035 на уникальность (обычно название организации на латинице без пробелов, например, «nashaorganizaciya»), можно оставить пустым - тогда он будет сгенерирован автоматически в виде уникального идентификатора;
- Ответственное за интеграцию лицо:
- ФИО;
- Телефон;
- Адрес электронной почты.
В течение 3 дней вы получите в ответ письмо с client_id (если вы его не указывали в запросе) и с секретным ключом.
Взаимодействие с провайдером аутентификации и авторизации (SSO)
Провайдер аутентификации и авторизации (SSO) является сервисом авторизации, работающим по протоколу OAuth2.
Для начала взаимодействия необходимо выполнить последовательно действия по подключению к SSO, сообщив идентификатор приложения (client_id) и ссылку перенаправления (redirect_uri), получив в ответ токен.
При аутентификации веб-приложений во время прямого взаимодействия с пользователем используется аутентификация при помощи OAuth2, и в этом случае информацию из профиля пользователя можно получить по ссылке users/me.
URL SSO для тестового контура https://sso.u2035test.ru.
URL SSO для продакшена https://sso.2035.university.
Начало процесса авторизации
GET
/oauth2/authorize?client_id=<client_id>&redirect_uri=<redirect_uri>&response_type=code</redirect_uri></client_id>
где:
- CLIENT_ID - идентификатор приложения, зарегистрированного в SSO;
- REDIRECT_URI - адрес, на который будет перенаправлен пользователь.
Здесь и ниже значение параметра REDIRECT_URI должно совпадать со значением, переданным при подключении, если будет отличаться, то будет возвращен код ошибки.
Получение sso_access_token
POST /oauth2/access_token
-H"content-type: application/x-www-form-urlencoded"
Тело запроса:
client_id=<client_id>&client_secret=<client_secret>&code=<your_code_from_authorize>&grant_type=authorization_code&redirect_uri=<redirect_uri></redirect_uri></your_code_from_authorize></client_secret></client_id>
где:
- CLIENT_ID - идентификатор приложения, зарегистрированного в SSO;
- CLIENT _SECRET - токен для SSO, получаемый при выполнении порядка подключения к API;
- YOUR_CODE_FROM_AUTHORIZE - code, полученный в ответе на запрос в пункте «Начало процесса авторизации»;
- REDIRECT_URI - адрес, на который будет перенаправлен пользователь после авторизации в SSO.
Запрос идентификатора пользователя (leader_id, unti_id)
GET /users/me
-H"Authorization: Bearer <sso_access_token></sso_access_token>
SSO_ACCESS_TOKEN - токен, полученный в ответе на запрос в пункте «Получение sso_access_token».
Формат ответа:
- unti_id (int) id пользователя
- email (str) емейл
- lastname (str) фамилия
- firstname (str) имя
- secondname (str) отчество
- gender (str) male|female
- leader_id (str) id пользователя в leader-id
- tags (list) список тегов пользователя
Пример бэкенда для python https://pastebin.com/F3Z5MFSz
Пример бэкенда для PHP (moodle плагин) https://github.com/u2035/moodle-sso-oauth
Из ответа необходимо выбрать только leader_id и записать в учетные данные пользователя, чтобы в дальнейшем вместе со сведениями о нём передавать и этот параметр.
Пример ответа:
* {
"unti_id": 1,
"email": "user@example.com",
"lastname": "Иванов",
"firstname": "Иван",
"secondname": "Иванович",
"gender": "male",
"leader_id": "123456",
"tags": ["assistant"]
}
* 401 если пользователь не авторизован
Обращаем ваше внимание, что email адрес не проходил валидации с нашей стороны.
Тестирование
Для подтверждения того, что вы успешно прошли авторизацию в тестовом контуре, вам нужно будет в запросе на доступ к продуктовому контуру указать ваш Leader ID и содержание ответа «GET /users/me» для данного пользователя.
Для получения консультации по интеграции в рамках тестового контура необходимо с корпоративного адреса электронной почты ответить на ранее направленное письмо на apps@2035.university с сутью вопроса, приложив по возможности скриншоты/скринкасты до и после описываемого события, url и параметры запросов.
Частые ошибки
Ошибка:
Сервис отвечает “invalid_request The requested redirect didn't match the client settings.”
Решение:
В запросе указали неверный redirect_uri (отличающийся от указанного в запросе на доступ). Напишите письмо с просьбой изменить его.
Указанный в запросе redirect_uri, должен точно совпадать с прописанным в настройках клиента (например, если в клиенте https://staging.experts.work/, а в запросе http://staging.experts.work/ или https://staging.experts.work или https://staging.experts.work/auth/callback/, вы получите ошибку)
Гайд по использованию элементов дизайна 2035
Все представленные логотипы и иконки находятся по ссылке:
https://files.2035.university/d/348c80581f1c47d9b605/?p=%2FUniversity%2020.35&mode=list
Логотип
Цвета
Шрифт
Текстовое написание
1. Университет 20.35
Допустимое сокращение, если действительно нет возможности разместить полное название «У 20.35». Но подобное сокращение должно сопровождаться логотипом или иконкой.
Круглые иконки
Квадратные иконки
Кнопки входа
Загрузка цифрового следа с использованием API к LRS
Этапы интеграции с Университетом 2035
Для интеграции с LRS Университета 2035 необходимо последовательно совершить следующие действия:
- Запросить доступ к тестовому хранилищу LRS, в которое вы будете загружать данные. Если вы работаете с нами по нескольким проектам, для каждого проекта нужно отдельное хранилище. Правила выдачи прав доступа описаны ниже.
- Протестировать передачу в LRS полного пакета стейтментов по одному пользователю. Подробно описан ниже. Процесс тестирования двухсторонний, с участием технических специалистов Платформы 2035 и провайдера.
- Запросить доступ к хранилищу LRS на продуктовом контуре. После получения доступа вы сможете загружать ЦС на на продуктовом контуре.
Как получить доступ к тестовому хранилищу
Направьте заявку на выдачу токена письмом на электронную почту apps@2035.university:
- Тема: Доступ к тестовому External LRS, название организации.
- Текст: Просим выдать логин, пароль и basic auth токен к External LRS.
- Для какого контура: Тестовый.
- Организация (юридическое наименование, как в договоре).
- Название проекта, в рамках которого проходит интеграция.
В ответ вы немедленно получите автоответ от нашего саппорта, что заявка принята. Затем в течение 3 дней заявка будет обработана, и вы получите письмо с информацией, необходимой для доступа. Сразу после этого вы можете приступать к тестированию передачи ЦС.
Обратите внимание!!! Отсутствие части информации в заявке влияет на скорость (замедляет) принятия по ней решения
Этапы тестирования интеграции с тестовым стендом LRS Университета 2035
В Университете 2035 используется LRS (Learning Record Store, хранилище учебных активностей) под названием «Learning Locker».
Документация на английском языке тут: http://docs.learninglocker.net/welcome/.
Интеграция с LRS Университета 2035 заключается в 2-х аспектах:
- Настройка инструмента оправки запросов к RESTful API на стороне LRS.
- Отправка фактов в LRS;
- Получение фактов из LRS.
- Настройка шаблонов отправки сообщений (xAPI) для каждого фиксируемого факта.
Перед началом подключения к API LRS вы получили параметры доступа к нему, которые должны выглядеть так:
- xAPI Endpoint: https://lrs-external.u2035test.ru/data/xAPI
- Key: ffcdf8e906c2975e299e305cc695b92bdd4251f1
- Secret: b7970235d91ee57a382a75dddd825ce8732abb9b
- Basic: ZmZjZGY4ZTkwwwMyOTc1ZTI5OWUzMDVjYzY5NWI5MmJhZTQyNTFmMTpiNzk3MDIzNWQ5MWVlNTdhMzgyYTc1ZWVlZDgyNWNlODczMmFiYjli
Пояснения к параметрам:
- Первый параметр для всех организаций одинаковый – это адрес API тестового стенда LRS Университета 2035.
- Второй, третий и четвертый – индивидуальные для каждого хранилища для каждой организации (на стороне LRS для организации может быть настроено несколько хранилищ). Приведены измененные параметры только для того, чтобы был пример, как они должны выглядеть.
- Используется либо 2-й и 3-й параметры, либо 4-й, они являются взаимозаменяемыми, только два первых указываются в полях логин и пароль некоторых инструментов отправки REST-запросов, а последний тоже самое только в base64-кодировке и используется в параметре Authorization заголовка запроса.
Ниже по тексту будут представлены в качестве примеров скриншоты из бесплатного инструмента работы с REST API Postman.
Настройка параметров и проверка связи
Необходимо в средстве/механизме оправки REST запросов указать Адрес API (первый параметр выше + /statements).
Параметры заголовка - параметры авторизации (2-3 или 4 параметры указанные выше).
Обязательные параметры:
Key | Value |
|---|---|
X-Experience-API-Version | 1.0.3 |
content-type | application/json |
Для проверки связи выполните следующие действия:
- Отправить запрос «Get» с указанными на предыдущем этапе данными. В ответ должен вернуться статус 200 (ОК).
- Если данные, указанные на предыдущем шаге указаны не верно, то в ответ на отправленный запрос отобразится статус ошибки:
- Не найден API, если адрес URL указан неправильно.
- 404 Not Found, если к адресу не добавили /statements.
- 400 Bad Request, если не указаны заголовки или указаны не верно (X-Experience-API-Version обязателен для любых запросов, content-type для Get не обязателен).
- 401 Unauthorized, если неправильно указали параметры авторизации
Вторым запросом для проверки подключения к LRS отправить запрос «POST» с ранее указанными параметрами и простым сообщением в теле запроса: {"Test":"тест"}. В ответ на такой запрос должен быть получен статус 400 Bad Request телом ответа:
{
"errorId": "aa9c8065-6884-48ac-adfd-b283f49e14ad",
"warnings": [
"Missing required value in 'statements.0.actor'",
"Missing required value in 'statements.0.verb'",
"Missing required value in 'statements.0.object'",
"Unknown keys (Test) set in 'statements.0'"
]
}
Данный ответ означает, что запрос был отправлен в LRS, но его структура не соответствует структуре xAPI, предполагающий обязательные элементы, описывающие факт: actor, verb и object.
Получение указанного ответа означает, что настройка и тестирование вашего средства/механизма отправки запросов в LRS завершено и нужно переходить к формированию корректных сообщений о фактах обучения в формате xAPI.
Как получить доступ на продуктовом контуре
Получение доступов на продуктовый LRS аналогичен получению доступа к тестовому хранилищу.
Направьте заявку на выдачу токена письмом на электронную почту apps@2035.university:
- Тема: Доступ к продуктовому External LRS, название организации.
- Текст: Просим выдать логин, пароль и basic auth токен к External LRS.
- Для какого контура: Продуктовый.
- Организация (юридическое наименование, как в договоре).
- Название проекта, в рамках которого проходит интеграция.
Обратите внимание!!! Отсутствие части информации в заявке влияет на скорость (замедляет) принятия по ней решения
В ответ вы немедленно получите автоответ от нашего саппорта, что заявка принята. Затем в течение 3 дней заявка будет обработана, и вы получите письмо с логином, паролем и секретным ключом.
Работа с файлами
Для отправки артефактов используется сервис s3.
Алгоритм взаимодействия следующий:
- по запросу выдаем доступ к сервису s3, который мы используем,
- подключаетесь и работаете с ним по стандартному протоколу,
- в ЦС в стейтменте xAPI передается ссылка на файл в этмо сервисе.
Доступ к s3 выдается одновременно с доступом к LRS.