Интеграция с GetCourse
Автоматическое создание и рассылка дипломов и сертификатов из GetCourse после окончания тренинга или вебинара. Ссылка на готовый диплом будет сохранена в данных ученика в GetCourse.
Создание процесса
Чтобы отправлять запросы на создания файлов в ГрамотаДел Express, необходимо создать процесс в GetCourse. Для этого нужно открыть "Задачи" - "Процессы". Далее - "Создать процесс". Заполнить название и выбрать "Тип объекта" - "Пользователи".
Окно создания процесса
Далее в процессе, нужно выбрать вкладку "Процесс" и справа "Добавить блок" - "Операция".
Окно создания процесса - добавление вызова URL
В появившемся окне следует выбрать "Вызвать URL" (самый последний пункт") и нажмите "Сохранить".
Окно создания процесса - окно задачи
Это основное окно. Нужно выбрать метод POST, а в поле URL укажите строку запроса, которая должна содержать:
- Адрес запроса - https://gramotadel.express/api/v1/create/?
- Токен API - secure (взять в настройках, в ГрамотаДел Express)
- ID документа - doc_id Документ, на основании которого будет выдан сертификат или диплом
- ID папки - folder_id Папка на Диске, в которую нужно будет положить файл
- ID письма - mail_id Шаблон письма, который будет использоваться для отправки файла
- Данные для замены, каждая переменная, начинающиеся с mask_
Вначале рассмотрим все эти данные подробнее, а затем - как в итоге должна выглядет строка запроса.
Переменные
В запросе должны быть переменные, которые обеспечивают доступ к аккаунту в ГрамотаДел Express, указывают на то, какой документ использовать, в какую папку в Диске сохранять файл и так далее.
Обязательные переменные формы помечены звёздочкой.
-
secure*
Токен (строка, 36 символов) со страницы "Токены API" в ГрамотаДел Express
-
doc_id*
ID документа (строка, 36 символов), который будет использоваться для создания файла. ID можно получить в адресной строке, когда документ открыт. Документ не должен быть в корзине, но может лежать в любой паке Документов.
-
email_send
Время, когда отправлять письмо с файлом. Может принимать следующие значения:
onfinish - Разослать все письма после создания всех файлов (по-умолчанию)
oncreate - Отправлять письма сразу же после создания файла. При создании одного файла onfinish и oncreate идентичны.
timeout - Разослать письма через промежуток времени. В этом случае необходимо передать ещё два параметра:
email_timeout_value - цифровое значение промежутка, через который отправлять письма, целое значение
email_timeout_value - единица измерения промежутка. Может принимать значение "m" (минуты), "h" (часы), "d" (дни).
Либо, для указания точного времени отправки, нужно передать время в формате unix time в email_timeout_timestamp. Если переданы timeout и email_timeout_timestamp, то приориет будет у последней. -
folder_id
ID папки в Диске (строка, 36 символов) сохранения файлов. Если папки нет, то она будет создана автоматически при создании первого файла.
-
page_id
Порядковый номер листа (число или строка), если в документе есть несколько листов. Можно передать один номер ( первый лист - 0), или номера (через запятую) листов, которые нужно использовать для создания файла.
-
result
Определяет в каком виде возвращать результат. Может принимать значения:
- Значение отсутствует. Будет возвращена JSON-строка с результатом запроса (см. ниже)
- link. При успешном запросе будет возвращена строка, содержащая ссылку на созданный файл (если в запросе было создание нескольких файлов, то ссылку на первый). Для получения самого файла нужно обратиться по указанной ссылке. На подготовку самих файлов требуется время - от 1 до 5 секунд на каждый файл. До того, как файл будет создан, запрос по этому адресу будет возврашать ошибку 404. Если запрос не привёл к созданию файла, то будет возвращена JSON строка с ошибкой (см. ниже).
- file. При успешном запросе будет возвращён сам готовый файл (если в запросе было создание нескольких файлов, то только первый). Так как создание файла занимает 1-5 секунд, то возврат произойдёт только после того, как файл будет создан. При большом количестве запросов к API время создание файла будет увеличено. Если файл не будет подготовлен за 30 секунд, то API вернёт ошибку 404 (хотя сам запрос на создание файла в конечном итоге будет исполнен). Если запрос не привёл к созданию файла, то будет возвращена JSON строка с ошибкой (см. ниже). Если ожидается, что запросов к API будет больше, чем 1 запрос в 5 секунд, то не стоит использовать этот параметр.
mail_id
ID шаблона письма (строка, 36 символов) для отправки по электронной почте. ID можно получить в адресной строке, когда шаблон открыт. Если переменная не передана, то письмо отправлено не будет.
Переменные
В документе ГрамотаДел Express должна быть хотя бы одна переменная для замены, например %name или %city. Переменная должна быть написана латиницей. Кирилические %фио или %класс использовать нельзя. Адрес электронной почты - %email.
При составлении URL в процесах имя переменной должно начинаться со слова mask_, и далее - переменная из Документа. Например, если в документе переменная %name, то имя переменной в URL - mask_name, если у документе переменная %city, то имя переменной - mask_city. Указанные для этих переменных данные будут доставлены в Документ в ГрамотаДел Express при создании файла.
Сами данные можно взять из того, что предоставляет GetCourse, список вот на этой странице (подзаголовок Переменные по объекту «Пользователи»). Значение должно быть в фигурных скобках, с префиксом object., например {object.first_name}
Если необходимо отправлять готовый файл по электронной почте, то следует использовать переменную mask_email, а значение - {object.email}, а если задать имя готового файла - mask_filename.
Таких переменных в документе может быть любое количество. Можно передать в ГрамотаДел любые данные из профиля пользователя в GetCourse, в том числе и из дополнительных полей, чтобы затем их нанести на готовый файл.
Если нужно вставить текущую дату, случайный номер или другие данные - то следует использовать функции.
Составление строки запроса
Итак, теперь можно составить строку URL для Задачи. Лучше это делать в любом редакторе, а затем скопировать в поле URL в Задаче. URL запроса может выглядеть так (цвета для удобства):
Разберём строку по-порядку:
- https://gramotadel.express/api/v1/create/? - адрес запроса
- mask_name={object.last_name}%20{object.first_name} - в переменную %name в документе будет подставлены имя и фамилия из профиля в GetCourse. Обратите внимание, что между именем и фамилией нужен пробел. Его обозначение - %20
- mask_city={object.city} - в переменную %city в документе будет подставлен город из профиля в GetCourse
- mask_level={object.Уровень} - в переменную %level в документе будет подставлено значение из дополниельного поля "Уровень", из профиля в GetCourse
- mask_email={object.email} - адрес электронной почты посетителя из профиля в GetCourse
- doc_id=b75b01cf-c732-49c6-80a0-77dd051a8299 - ID Документа в ГрамотаДел Express
- folder_id=5a390b28-9845-4c01-b94a-7d252b115e2e - ID папки в Диске в ГрамотаДел Express
- mail_id=fb5eff48-4c08-4df7-a9e6-29e17896317c - ID шаблона письма в ГрамотаДел Express
- secure=8453bc41-с34у-4ead-80e8-c4e76175a11b - API секретный код из ГрамотаДел Express
Между переменными - знак &. Пробелы использовать нельзя. Очень, очень внимательно слудет составить строку, подставив свои данные и не потеряв ни одного символа. После сохранения Задачи, соедените "Начало работы" и "Задачу".
Окно создания процесса - процесс
В настройках ГрамотаДел Express нужно включить приём запросов через API и затем выполните тестирование. Для этого, в GetCourse, там же, в Процессе, нажмите "Тестировать", выберите аккаунт, и поставьте галочку "Выполнять действия по настоящему". Если всё верно, в результате в папке на Диске появится файл диплома или сертификата. Если вы указали mail_id, то файл будет отправлен на электронную почту. Если файл не появился, в окне тестирования будет написана причина, почему запрос не выполнился.
Завершение настройки процеса
Если тестирование успешно, файл создался и все данные подставились, можно завершить настройку процесса. Для этого нужно вернуться на вкладку "Основные". В панели "Массовое создание задач", укажите "Переодическая проверка", а в "Правило вхождения объекта" - когда срабатывать процессу выдачи сертификата. Например - "Участник трегинга", выберите какой трениг, и "Завершил". В результате, GetCourse будет проверять все посетителей, кто завершил указанный трениг, и, если так оно и есть - запускать указанный процесс. В настройках Тренинга в GetCourse, обязательно укажите когда считать тренинг завершённым. После запуска процесса новые задачи будут добавляться для тех посетителей, кто соответствует условиям поиска. Обратите внимание, что GetCourse делает проверку один раз в 5-15 минут. Это значит, что если посетитель завершил трениг, то сам сертификат он получит в течение 15 минут (ГрамотаДел обрабатывает запро сразу же).
Как сделать, чтобы под процесс не попали все текущие посетители, которым уже выдан диплом через GetCourse или вручную? Там же, в "Правило вхождения объекта", добавьте ещё одно условие, нажав "и", и, например "Дата регистрации", укзав нужную дату, или группу посетителя.
Добавление в группу после выдачи сертификата
Если необходимо, в GetCourse можно создать группу "Сертификат выдан", в "Пользователи" - "Группы" и добавлять всех пользователей в эту группу, кому был выдан сертификат через ГрамотаДел. Для этого, в процессе, после выполнения запроса на URL, добавьте ещё один блок, операцию, "Добавить в группу", и укажите эту группу. Затем свяжите запрос к URL и добавление в групу. В результате, после выполнения запроса посетитель будет добавлен в нужную группу.
Сохранение ссылки на сертификат в профиле пользователя GetCourse
Если необходимо, в GetCourse вы можете сделать сохранение ссылки на диплом или сертификат в профиле пользователя, которому был выдан сертификат. Для этого добавьте дополнительное поле "Сертификат" в "Пользователи" - "Дополнительные поля" - "Добавить поле" - "Строка". Затем, в URL запроса в ГрамотаДел добавьте &result=link, а ниже в том же окне - "Записать результат в доп. поле" и выберите это поле. В результате после запроса ссылка на диплом будет добавлена в профиль посетителя.
Ручное одобрение выдачи сертификатов
Если вы хотите вручную проверять ФИО или другие данные, перед тем как выдать сертификат, то это можно сделать двумя путями.
Путь первый: в процессе, в окне с url поставьте галочку в "Менеджер должен подтвердить запуск". В итоге менеджер должен будет одобрить запуск задачи для конкретного посетителя.
Путь второй: создать три группы "Ожидание сертификата", "Выдать сертификат" и "Сертификат выдан". Затем, в процессах - два процесса. Первый процесс должен срабатывать, когда посетитель заканчивает тренинг и он должен добавляться в группу "Ожидание сертификата", а второй процесс - это запрос в ГрамотаДел, при условии, если посетитель есть в группе "Выдать сертификат". В том же процессе нужно добавить ещё две операции - удаление из группы "Выдать сертификат" и добавление в "Сертификат выдан". В итоге, после прохождения курса посетитель будет добавлен в группу "Ожидание сертификата", затем менеджер должен будет проверить все данные и перенести посетителя в группу "Выдать сертификат". Как только задача будет создана, посетитель будет перемещён в группу "Сертификат выдан".