Категории

Инструкция по интеграции с цифровой платформой УНТИ 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, если неправильно указали параметры авторизации.