Интеграции / Пользовательские расширения

Пользовательские расширения

Помимо готовых интеграций в QuickBPM предусмотрена возможность добавить свои собственные расширения для интеграции с сервисами рассылки SMS и VoIP телефонией.

Для того, чтобы добавить интеграцию, перейдите в Администрирование > Интеграции и нажмите кнопку +Интеграция.

integration_2

Загрузите архив с готовым расширением или добавьте его из раздела Файлы.

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

integration_1

После успешной установки ваше расширение добавится в список интеграций в разделе Администрирование > Интеграции.

Требования к расширению

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

Формат ответа

Результат запуска интеграции должен быть записан в глобальный объект Context.data.result.

Формат объекта:

HttpCode - http статус ответа, по умолчанию 200

Headers - объект с заголовками

Data - данные ответа

Файлы общего назначения

 

Файл utils.ts

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

Файл hook.ts

Этот файл используется для кода, обрабатывающего хуки QuickBPM и хуки внешних систем.

Для обработки обращения из внешней системы необходимо объявить функцию:

начало примера

/**

* запуск бекенд хука

* @constructor

*/

function HandleHook(payload: any): Promise<void> {

}

конец примера

Для обработки обращения из системы необходимо объявить функцию:

начало примера

/**

* запуск фронт-хука из нашей системы

* @param action - действие

* @param args - аргументы, которые мы отправили

* @param settings - текущие настройки интеграции

* @constructor

*/

async function HandleFrontHook(action: string, args: any, settings: any)

конец примера

Файл schema.ts

Этот файл используется для добавления динамики в форму настроек. Обработка происходит в функции:

начало примера

/**

* AttachSchemaDetails - вызывается при изменении настроек, можно управлять настройками полей, их количеством, динамически

* изменять содержимое формы

* @param schema - список блоков формы

* @param data - данные формы

* @constructor

*/

async function AttachSchemaDetails(schema: any[], data: any): Promise<void> {

}

конец примера

В процессе работы этой функции необходимо записать новую схему формы настроек в Context.data.result.data.settingsSchema. Новая форма должна быть указана в том же формате, что и в файле schema.ts

Файл функций VoIP телефонии voip.ts

Данный файл необходим для интеграций VoIP телефонии, в нем обязательно реализовать следующие функции:

начало примера

/**

* метод проверки подключения

* @param apiKey

* @constructor

*/

async function TestConnection(apiKey: string) {

}

конец примера

начало примера

/**

* метод генерации звонка

* @param apiKey

* @param srcPhone

* @param dstPhone

* @constructor

*/

async function GenerateCall(apiKey: string, srcPhone: string, dstPhone: string) {

}

конец примера

начало примера

/**

* получение участников, контактов из провайдера

* @param apiKey

* @constructor

*/

async function GetMembers(apiKey: string) {

}

конец примера

начало примера

/**

* генерация ссылки на звонок

* @param apiKey

* @param callData - может принимать любой формат в зависимости от провайдера

* @constructor

*/

async function GetCallLink(apiKey: string, callData: unknown) {

}

конец примера

начало примера

/**

* обработка хука

* @param contentType - тип контента, заголовок, некоторые провайдеры присылают и форму, и json

* @param body – json, содержащий formData или json контент

* @constructor

*/

async function ParseWebhookRequest(contentType: string, body: string) {

}

конец примера

Файл функций SMS интеграции sms.ts

Этот файл обязателен для интеграций SMS сервисов. Он должен содержать функции:

начало примера

// Основной скрипт для работы вызовов

// SendSMS - обязательный метод отправки смс

async function SendSMS(phones: string[], text: string): Promise<void> {

}

// TestConnection - обязательный метод проверки соединения

async function TestConnection(): Promise<void>{

}

конец примера

Файл настроек schema.json

Этот файл содержит схему формы на странице настроек. Форма состоит из блоков, каждый блок может иметь имя, описание и набор полей:

начало примера

{

 "name""Соедениение",

 "description""Настройки соединения",

 "fields": [

   {"code""apiKey""required"true"type""STRING""view": {"name":  "API Key"}},

   {"code""password""required"true"type""STRING""view": {"name":  "Password"}}

 ]

}

конец примера

Файл манифеста интеграции, manifest.json

Описание манифеста должно храниться в отдельном документе.