Категории

Инструкция по интеграции с цифровой платформой УНТИ 2035

Инструкция по интеграции с цифровой платформой УНТИ 2035

Общие сведения и используемая терминология

Цифровой след, ЦС – это данные об образовательной, профессиональной или иной деятельности человека, представленные в электронной форме.
Цифровой след в рамках проведения проекта используется для установления фактов обучения и необходим для выполнения условий договора о предоставлении образовательных услуг.
Цифровой след передается в формате xAPI (https://xapi.com/).

Слушатель - получатель поддержки, студент, обучающийся.

ОО, Провайдер - образовательная организация, предоставляющая образовательные программы в рамках проекта.

LMS - Learning management system, образовательная система.

LRS - Learning record storage, хранилище цифровых следов.

Unti_id - идентификатор слушателя на платформе Университет 2035, УНТИ - unti.

Состав передаваемого цифрового следа проекта "Код будущего"

Номенклатура передаваемого цифрового следа проекта Код будущего

  1. Деятельность слушателя и её оценка, включая
  1. Просмотр видеоконтента и участие в онлайн вебинарах
  2. Рефлексии оставленные слушателем по итогу всех модулей и курса

Необходимым для получения поддержки за обучение слушателя являются цифровые следы:

  1. Оценка результатов итоговой деятельность, включающую
  1. Рефлексии оставленные слушателем по итогу всех модулей и курса целиком, включающие проверки текста рефлексий на содержание, включающие

Интерфейсы загрузки ЦС на Платформу Университет.2035

На платформе 2035 цифровой след хранится в LRS (learning record storage) - специализированном хранилище данных о цифровом следе пользователя. LRS предоставляет API для загрузки цифрового следа.

Возможны несколько вариантов загрузки цифрового следа в LRS:

  1. LMS автоматизировано отправляет необходимые цифровые следы в формате xAPI либо дорабатывая собственную LMS, либо устанавливая плагины в LMS.
  1. возможна передача предподготовленных файлов в формата xAPI, содержащие множество цифровых следов, в систему Университета.2035.
  2. возможна передача передача цс в виде табличных шаблонов через личный кабинет организации в системе Cat.

Для получения идентификаторов студентов unti_id предварительно необходимо реализовать интеграцию с системой аутентификации и авторизации (SSO) Платформы Университета 2035.

Для загрузки файлов, содержащих итоговую (и другую) деятельность слушателей, предварительно необходимо реализовать интеграцию с хранилищем S3 Платформы Университета 2035.

Этап 1. Интеграция с системой аутентификации и авторизации (SSO)

Шаги интеграции ОО с SSO платформы:

  • запросить доступ к API SSO на тестовом контуре и дождаться ответа с секретным ключом,
  • реализовать логику обращения к нашему API SSO,
  • добавить на сайт кнопку авторизации с учетом гайда по использованию элементов дизайна 2035,
  • протестировать взаимодействие с нашим API на тестовом контуре;
  • запросить доступ к API SSO в промышленном контуре (prod, production) и дождаться ответа с секретным ключом.

Обратите внимание! Для работы необходимо на заключительном этапе получить доступ именно к промышленному контуру.
Неприятная ошибка, - продолжить слать рабочие цифровые следы в тестовый контур, их придется повторно послать в промышленный контур.

Для получения консультации по интеграции необходимо с корпоративного адреса электронной почты написать письмо на apps@2035.university с сутью вопроса.
В письме приложите все необходимое для комплексного рассмотрения ситуации: скриншоты/скринкасты до и после описываемого события, url и параметры запросов, версия браузера и т.п.

1.1. Запросы доступа к API SSO

Запросы на тестовый и продуктовый контур имеют одинаковый формат, дополнительно при запросе доступов на прод необходимо приложить ответ метода users/me на тесте.
Необходимо с корпоративного адреса электронной почты отправить письмо на apps@2035.university следующего содержания:

  1. Тема письма: Подключение к API SSO Полное наименование организации. Тестовый/Промышленный контур;
  2. Текст письма:
  • Наименование организации: Полное наименование организации;
  • Проект: Проект;
  • Контур: тестовый/промышленный;
  • Домен/ссылка сервиса (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 (если вы его не указывали в запросе) и с секретным ключом.

1.2. Взаимодействие с провайдером аутентификации и авторизации (SSO)

Провайдер аутентификации и авторизации (SSO) является сервисом авторизации, работающим по протоколу OAuth2.

Для начала взаимодействия необходимо выполнить последовательно действия по подключению к SSO, сообщив идентификатор приложения (client_id) и ссылку перенаправления (redirect_uri), получив в ответ токен.

При аутентификации веб-приложений во время прямого взаимодействия с пользователем используется аутентификация при помощи OAuth2, и в этом случае информацию из профиля пользователя можно получить по методу users/me.

URL SSO для тестового контура https://sso.u2035test.ru.
URL SSO для продакшена https://sso.2035.university.

1.2.1. Начало процесса авторизации

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 должно совпадать со значением, переданным при подключении, если будет отличаться, то будет возвращен код ошибки.

1.2.2. Получение 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.

1.2.3. Запрос идентификатора пользователя (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 адрес не проходил валидации с нашей стороны.

1.3. Тестирование

Для подтверждения того, что вы успешно прошли авторизацию в тестовом контуре, вам нужно будет в запросе на доступ к продуктовому контуру указать ваш Leader ID и содержание ответа «GET /users/me» для данного пользователя.

Для получения консультации по интеграции в рамках тестового контура необходимо с корпоративного адреса электронной почты ответить на ранее направленное письмо на apps@2035.university с сутью вопроса, приложив по возможности скриншоты/скринкасты до и после описываемого события, url и параметры запросов.

1.4. Частые ошибки интеграции с SSO

Ошибка:
Сервис отвечает “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/, вы получите ошибку)!

1.5. Материалы по использованию элементов дизайна 2035

Все представленные логотипы и иконки находятся по ссылке: https://files.2035.university/d/348c80581f1c47d9b605/?p=%2FUniversity%2020.35&mode=list

Логотип


Цвета


Шрифт


Круглые иконки


Квадратные иконки


Кнопки входа


Использование текстового написания нашей организации - Университет 20.35

Допустимое сокращение, если действительно нет возможности разместить полное название «У 20.35». Но подобное сокращение должно сопровождаться логотипом или иконкой.

Этап 2. Загрузка цифрового следа с использованием API к LRS

2.1. Общая инструкция интеграции к LRS

Шаги интеграции ОО с LRS платформы:

  1. Запросить доступ к тестовому хранилищу LRS.
    Если вы работаете с нами по нескольким проектам, для каждого проекта нужно отдельное хранилище. Правила выдачи прав доступа описаны ниже.
  2. Протестировать передачу в LRS полного пакета стейтментов по одному пользователю. Подробно описан ниже.
    Процесс тестирования двухсторонний, с участием технических специалистов Платформы 2035 и провайдера.
  3. Запросить доступ к хранилищу LRS на промышленном контуре.
    После получения доступа вы сможете загружать ЦС на промышленном контуре.

Обратите внимание! Для работы необходимо на заключительном этапе получить доступ именно к продуктовому контуру.
Неприятная ошибка, - продолжить слать рабочие цифровые следы в тестовый контур, их придется повторно послать в промышленный контур.

2.2. Доступ к тестовому хранилищу LRS (тестовый контур)

Направьте заявку на выдачу токена письмом на электронную почту apps@2035.university:

  1. Тема: Доступ к тестовому External LRS, название организации.
  2. Текст: Просим выдать логин, пароль и basic auth токен к External LRS.
  3. Для какого контура: Тестовый.
  4. Организация (юридическое наименование, как в договоре).
  5. Название проекта, в рамках которого проходит интеграция.
  6. ID организации на Платформе (в ЛК Каталога).

В ответ вы немедленно получите автоответ от нашего саппорта, что заявка принята.
Затем в течение 3 дней заявка будет обработана, и вы получите письмо с информацией, необходимой для доступа.
Сразу после этого вы можете приступать к тестированию передачи ЦС.

Обратите внимание!!!

Отсутствие части информации в заявке влияет на скорость (замедляет) на работу по ней

2.3. Тестирование авторизации LRS (тестовый контур)

В Университете 2035 используется LRS (Learning Record Store, хранилище учебных активностей) под названием «Learning Locker».

Документация на английском языке тут: http://docs.learninglocker.net/welcome/.

Интеграция с LRS Университета 2035 заключается в 2-х аспектах:

  1. Настройка инструмента оправки запросов к RESTful API на стороне LRS.
  1. Настройка шаблонов отправки сообщений (xAPI) для каждого фиксируемого факта.

Перед началом подключения к API LRS вы получили параметры доступа к нему, которые должны выглядеть так:

  1. xAPI Endpoint: https://api.u2035test.ru/lrs-external/data/xAPI/
  2. Basic: ZmZjZGY4ZTkwwwMyOTc1ZTI5OWUzMDVjYzY5NWI5MmJhZTQyNTFmMTpiNzk3MDIzNWQ5MWVlNTdhMzgyYTc1ZWVlZDgyNWNlODczMmFiYjli
  3. Key: ffcdf8e906c2975e299e305cc695b92bdd4251f1
  4. Secret: b7970235d91ee57a382a75dddd825ce8732abb9b

Пояснения к параметрам:

  1. Первый параметр для всех организаций одинаковый – это адрес API тестового стенда LRS Университета 2035.
  2. Второй, третий и четвертый – индивидуальные для каждого хранилища для каждой организации (на стороне LRS для организации может быть настроено несколько хранилищ).
    Приведены измененные параметры только для того, чтобы был пример, как они должны выглядеть.
  3. Используется либо 2-й, либо и 3-й и 4-й параметры, они являются взаимозаменяемыми. 3-й и 4-й указываются в полях логин и пароль некоторых инструментов отправки REST-запросов, 2-й тоже самое только в base64-кодировке и используется в параметре Authorization заголовка запроса.

Ниже по тексту будут представлены в качестве примеров скриншоты из бесплатного инструмента работы с REST API Postman.

Обратите внимание!!!

Для проверки работоспособности вы можете использовать проект в postman, в котором собраны необходимые шаблоны для интеграции

https://www.postman.com/university2035/workspace/digital-profession/request/13155775-a2ddcc09-b36f-48aa-9aca-051835d29ebb

В частности для проверки работоспособности полученных ключей авторизации используйте шаблон "Проверка связи"

2.4. Настройка параметров и проверка связи

Необходимо в средстве/механизме оправки REST запросов указать Адрес API (первый параметр выше + /statements).

Параметры заголовка - параметры авторизации (2 или 3,4 параметры указанные выше).


Обязательные параметры:

Key

Value

X-Experience-API-Version

1.0.3

content-type

application/json


Для проверки связи выполните следующие действия:

  1. Отправить запрос «Get» с указанными на предыдущем этапе данными. В ответ должен вернуться статус 200 (ОК).
  2. Если данные, указанные на предыдущем шаге указаны неверно, то в ответ на отправленный запрос отобразится статус ошибки:a. Не найден API, если адрес URL указан неправильно. b. 404 Not Found, если к адресу не добавили /statements. c. 400 Bad Request, если не указаны заголовки или указаны неверно (X-Experience-API-Version обязателен для любых запросов, content-type для Get не обязателен). d. 401 Unauthorized, если неправильно указали параметры авторизации.

3. Вторым запросом для проверки подключения к 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'"
]
}
Обратите внимание! Метод уже не GET, а POST
Данный ответ означает, что запрос был отправлен в LRS, но его структура не соответствует структуре xAPI, предполагающий обязательные элементы, описывающие факт: actor, verb и object.
Получение указанного ответа означает, что настройка и тестирование вашего средства/механизма отправки запросов в LRS завершено и нужно переходить к формированию корректных сообщений о фактах обучения в формате xAPI.
4. В дальнейшем вы можете, например, попробовать разные шаблоны из проекта Postman, чтобы познакомиться со структуру xapi и удостовериться в их работоспособности

2.5. Использование xAPI

Обратите внимание!

Ознакомьтесь с документом-таблицей, в которой приведены необходимые шаблоны цифрового следа используемые в Университете 20.35.

Для проекта Цифровые профессии используются шаблоны-вкладки "Деятельность и её оценка" и "Просмотр видео".

https://docs.google.com/spreadsheets/d/1ACEN9ewnUSJdf9zpGHjK5I_7NSFH0OprN2PmsOy_Gn0/edit#gid=1962238928

Колонки B C шаблона содержат непосредственно statement, готовы для копирования, преобразования beautify, и отправки как statement.
Колонка D содержит необходимые комментарии по использованию полей.

Эти же шаблоны собраны собраны в проекте Postman:

https://www.postman.com/university2035/workspace/digital-profession/request/13155775-a2ddcc09-b36f-48aa-9aca-051835d29ebb.

2.6. Доступ в промышленный контур LRS

Получение доступов на промышленный контур LRS аналогичен получению доступа к тестовому хранилищу.

Направьте заявку на выдачу токена письмом на электронную почту apps@2035.university:

  1. Тема: Доступ к продуктовому External LRS, название организации.
  2. Текст: Просим выдать логин, пароль и basic auth токен к External LRS.
  3. Для какого контура: Промышленный.
  4. Организация (юридическое наименование, как в договоре).
  5. Название проекта, в рамках которого проходит интеграция.

Обратите внимание!!!

Отсутствие части информации в заявке влияет на скорость (замедляет) принятия по ней решения

В ответ вы немедленно получите автоответ от нашего саппорта, что заявка принята. Затем в течение 3 дней заявка будет обработана, и вы получите письмо с логином, паролем и секретным ключом.

Этап 3. Интеграция с S3. Работа с файлами

Обратите внимание, аттачменты необходимая часть для цифрового следа итоговой деятельности!
Для отправки артефактов используется сервис s3.
Алгоритм взаимодействия следующий:

  • По запросу на доступ к LRS выдаем доступ к сервису s3, который мы используем (если его нет - запросите отдельно на apps@2035.university, указав организацию и проект).
  • Подключаетесь и работаете с ним по стандартному протоколу.
  • Нужно проставлять у файлов 'ACL' => 'public-read'.
  • В ЦС в стейтменте xAPI передается ссылка на файл в этом сервисе.

В стейтменте xAPI нужно заполнить массив объектов в statement.attachments. В каждом объекте заполняется набор полей, ссылка на объект в s3 пишется в fileUrl:
usageType: string
display:
ru-RU: string
description:
ru-RU: string
contentType: string
length: int
sha2: string
fileUrl: string

Этап 4. (альтернатива 2.) Загрузка цифрового следа файлами в личном кабинете организации.

В Каталоге в ЛК ОО доступна загрузка файлов с ЦС в табличном виде.

Шаблоны собраны в документе https://docs.google.com/spreadsheets/d/138WguabAIqYHEI8xxD3birt-3UKEDIr7Bel_wCVoMGU/edit#gid=1192254874

4.1. Инструкция загрузки ЦС в табличном виде

Для загрузки цифрового следа перейдите в раздел «Работа с цифровым следом». Далее выберите курс, по которому планируете загружать цифровой след.


В открывшемся окне нажмите кнопку «Загрузить цифровой след». Обратите внимание, что в этом же интерфейсе в табличной части будет отображаться информация об уже загруженном цифровом следе.



В открывшемся окне выберите профиль и проект «Код будущего».



Далее вы можете добавить один или несколько элементов ЦС.
Для загрузки элемента нажмите «Добавить» и перейдите к выбору элемента цифрового следа, который собираетесь загружать. На проекте «Цифровые профессии 2021» вам нужно использовать следующие элементы (они подсвечены зеленым в выпадающем списке):

- Оценка результатов итоговой деятельности

- Оценка результатов аттестации

- Оценка результатов деятельности

- Входная диагностика / тестирование

- Данные о просмотре видеоконтента


Для загрузки одного элемента ЦС:

  1. выберите элемент ЦС в выпадающем списке,
  2. скачайте шаблон,
  3. заполните его и загрузите, нажав кнопку выбора файла,
  4. сохраните.


При загрузке элементов ЦС, в состав которых входят артефакты (Оценка результатов итоговой деятельности и Оценка результатов деятельности), также нужно загрузить архив с артефактами.

Правила формирования архива:

  • для каждого пользователя в соответствующем столбце указывается название файла(-ов) или архива,
  • если по одному пользователю предполагается несколько файлов, их необходимо указывать через разделители «,» «;» « »,
  • внутри архива не должно быть папок,
  • не допускается название на кириллице,
  • в названиях файлов не должно быть пробелов.

Если вы видите ошибку загрузки, разбейте файл на несколько. Длительность обработки файла зависит от текущей нагрузки на систему - возможно, вы как раз грузите файл в пиковое время.