Плагины – РосБизнесСофт CRM

Разработка плагинов

Плагином является модуль расширения функциональность Системы. Доступные пользователю плагины размещены в меню «Настройки» — «Интеграции» — «Загруженные».

Плагины могут быть разработаны вендором, партнером или самим клиентом.

Для добавления своего плагина в Маркет-плейс или в облачную версию Системы необходимо связаться с технической поддержкой по электронной почте: support@rbs-crm.ru.

В коробочной поставке разработчик самостоятельно добавляет плагин в систему (папка projects/xrm/plugins/).

Плагины бывают нескольких типов:

Телефония. Скачать пример
СМС. Скачать пример
Контентные. Скачать пример

Класс PluginBase

PluginBase — класс, от которого должны наследоваться все «index.php» в плагинах. Все классы, унаследованные от него, имеют возможность вызывать action%Method% через браузер напрямую, кроме зарезервированных.

Например, по ссылке /plugins/%PluginName%/test будет вызываться метод actionTest() в action.php.

В плагинах используется параметр APIKEY. Это уникальный ключ для доступа к плагинам извне, которые передается в заголовке HTTP-запроса в виде GET-параметра. APIKEY задается в меню «Настройки» — «Безопасность».

Свойства класса:

$actions = [] — Reference Action объектов плагина
$settings = []— Все настройки плагина. В том числе с BD
$plugin_id = 0 — ID плагина после установки
$this->DB — экземпляр класса Database (после инициализации)

Методы класса:

getName() — Метод, который должен быть в каждом плагине и возвращает: (string) %plugin_name%
actionIndex() — Метод, который должен быть в каждом плагине. Используется для вывода Описания. Вызывается, когда пользователь устанавливаем плагин в Маркет-плейсе.
getManifest() — Возвращает ассоциативный массив манифеста или []
checkActiveForm(string $formName) — Возвращает True/False, если форма есть в ActiveForms
eventInstall() — Вызывается после установки плагина и после сохранения параметров, если такие имеются
eventChangeSettings() — Вызывается каждый раз, когда сохраняются новые параметры в настройках Плагина пользователем
eventUninstall() — Вызывается перед удалением плагина
getData($configManifest = []) — Устанавливает $this->settings (Настройки плагина, в том числе по умолчанию) из базы данных. Устанавливает $this->plugin_id. Если $configManifest не задан, то автоматом получает через $this->getManifest()
getSettingsValue(string $key) — Получает параметр настройки Плагина по ключу $this->settings[$key] из БД. Если нет, то возвращает пустую строку.
setSettingsValue(string $key, string $value) — Устанавливает параметр настройки Плагина по ключу в БД. Все ключи должны быть прописаны в mantifest.settings.
deleteSettingsKey($key) — Удаляет значение параметра настройки Плагина по ключу из БД.
installPlugin() — Устанавливает плагин и синхронизирует настройки manifest.settings c БД
deletePlugin() — Удаляет все настройка плагина и деинсталирует его
isActive() — Проверяет, установлен или нет плагин в Системе
getRealName($nameAttr = «name»») — Получить имя с langpack. Если нет — берет $this->getName()
getFullPath() — Полный физический путь к плагину
getPath() — Относительный путь к плагину
getLangPack($defLang = null) — Получает массив LangPack. Если $defLang не задан — то берется язык по умолчанию из Системы
existAction(string $actionName) — Проверяет, есть ли action у данного объекта
getListByType($type, $checkActive = false)
Получает Action объекта установленного плагина, где $type — это тип Action:
- Kernel\Plugins\PluginManager::PLUGIN_TYPE_PHONE — Телефония
- Kernel\Plugins\PluginManager::PLUGIN_TYPE_SMS — СМС
- Kernel\Plugins\PluginManager::PLUGIN_TYPE_CONTENT — Другие
Если checkActive = true — то будет проверятся плагин на isActive()
getAction($actionName) — Получить объект PluginAction. $actionName = PluginManager::PLUGIN_TYPE_*
beforeDisplay() — Вызывается перед display() или выводом информации. Устанавливает $this->page. Также метод вызывается, если нужно передать в шаблон ряд переменных.
display($templateName) — Выводит шаблон $templateName который находится в папке html плагина
output($templateName, $isArray = false) — Тоже самое что и display(), только не выводит, а возвращает результат рендера шаблона.
getApiKey() — Получить APIKEY (см. меню «Настройки» — «Безопасность»).
resultSuccess($array = [], $resultOnlyData = false) — Возвращает Json/Xml ответ. Если $resultOnlyData выставить в «true», то будет результат массив $array, иначе полный заголовок result в системе со status и прочим. Сбивает $this->page на XML/JSON
resultError($error = [], $resultOnlyData = false) — Возвращает Json/Xml ошибку resultOnlyData, как и в resultSuccess
getCallbackLink(PluginManager::PLUGIN_TYPE_* $type, $action = «», $joinParams = []) — Получить полную внешнюю ссылку на %Type%Action Плагина с учетом API_KEY. Если $action установлен, то ссылку даст на actionMethod $Type%Action плагина. Параметр — $joinParams — это массив ключ=>значение. Добавляет get параметры к URL, при этом не затирая API_KEY. Параметры автоматически экранируются Urlencode. Обычно ссылка из getCallbackLink() используется для взаимодействия с Плагином из стороннего сервиса, например при отправке уведомления о входящем звонки из АТС, или для приема любого Webhook.
```
getCallbackLink(Kernel\Plugins\PluginManager::PLUGIN_TYPE_PHONE, string $action = "")
// http://xrm-dev-sp1/plugins/%pluginName%/%type%/%action%/?APIKEY=%API_KEY%

getCallbackLink(Kernel\Plugins\PluginManager::PLUGIN_TYPE_PHONE, $action = "dopaction", ["a" => "b"])
// http://xrm-dev-sp1/plugins/%pluginName%/phone/dopaction/?a=b&APIKEY=%API_KEY%
```
printCallbackLink(PluginManager::PLUGIN_TYPE_* $type, $action=»», $link = «», string $BLOCK = «») — Размещение CallbackLink в шаблоне. Если не установлен $link, то выполняется getBackLink(). $BLOCK — в каком блоке разместить ссылку. Если не указать значение в $BLOCK, то блок по умолчанию будет «CALLBACK_LINK». Если задать $BLOCK = «SUB_BLOCK», то фактически блок будет выглядеть так: «SUB_BLOCK.CALLBACK_LINK».
function printUsers($BLOCK = «») — Используется для рендера списка пользователей. Например в телефонии, для привязки сотрудников к коротким номерам службы.

Класс PluginAction

PluginAction — класс, от которого наследуются все Action.

Свойства класса:

После инициализации.

$this->DB — экземпляр класса Database
$this->User — экземпляр класса User
$this->Http — экземпляр класса Http,

Методы класса:

getDescription() — Получить описание Плагина. Проверяет есть ли оно в langPack, если нет то с манифеста берет
getPluginName() — Получить имя плагина
getLangPack() — Получить lang pack
getType() — Получить тип Плагина
getVendor() -Получить производителя Плагина(РБС или партнер)
getVersion() -Получить версию Плагина
getRating() — Получить рейтинг Плагина
getPlugin() — Получить свой экземпляр класса PluginBase
getFormatPhone($phone, $append=»8″) — Конвертирует телефон например: +7 248 222-22-22 в 82482222222. Восьмерка вставляется с аргумента $append
Transfer($url, $postData = [], $ssl = null, $isGET = false) — Отправить запрос по CURL (по протоколу HTTP(S).
$url — ссылка куда отправляется запрос. $postData — массив, который используется как для GET запроса так и для POST. Ассоциативный массив. $ssl — Определяет включать SSL или нет. Если установить null — то система автоматически определяет. $isGET — true/false GET или POST параметры в запросе.

Класс PluginPhoneBase

PluginPhoneBase — расширение класса PluginAction. От PluginPhoneBase должны наследоваться все PhoneAction

Константы:

CALL_IN ( 1 — для Входящих звонков)
CALL_OUT (2 — для Исходящих звонков)
CALL_MISSED (3 — для Пропущенных звонков)

Свойства:

Все свойства и методы PluginAction.

Собственные методы:

actionCall()

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

Метод принимает переменные POST:

$post = $_POST[‘name’];
$to = $this->getFormatPhone($_POST[‘to’]);

Функция должна вернуть JSON-массив:

[
 "name" => "NAME",
 "to" =>"PHONE TO",
 "from" =>"FROM",
 "status" => "Connected", //or Disconnected
 "pluginName" => $this->getPlugin()->getRealName()
]

Где:

FROM— внутренний номер сотрудника (добавочный номер в карточке Плагина), от которого совершается звонок: $this->getShortNumber($this->User->getEmployeeId());

actionInbound()

Данный метод должен быть реализован в каждом телефонном плагине для получения информации о входящем звонке. Этот метод вызывается внешней системой для Callback. См. ниже пример.

getShortNumber($user_id)

Получение короткого номера пользователя из настроек текущего плагина.

getAllUsersWithExtensions()

Получение массива из «ID» всех пользователя, у которых есть добавочный номер в плагине. Метод доступен в релизе 23.01 и выше.

getCompanyByPhone($phone)

Находит companies по номеру телефона (при входящем и исходящем звонке).

Возвращает массив:

[
 'companyId' => 0,              // Id контрагента
 'companyName' => '',           // Наименование контрагента
 'companyEmail' => '',          // E-mail контрагента
 'contactId' => 0,              // Id контактного лица
 'contactName' => '',           // Наименование контактного лица
 'contactEmail' => '',          // E-mail контактного лица
 'url' => '',                   // Ссылка на найденного контрагента или контактное лицо
 'urlName' => '',               // Тип ссылки (company || contact)
 'companyResponsibleId' => 0    // Id ответственного за контрагента
]

getContactByPhone($phone)

Находит contacts по номеру телефона (при входящем и исходящем звонке).

Возвращает массив:

[
 'companyId' => 0,              // Id контрагента
 'companyName' => '',           // Наименование контрагента
 'companyEmail' => '',          // E-mail контрагента
 'contactId' => 0,              // Id контактного лица
 'contactName' => '',           // Наименование контактного лица
 'contactEmail' => '',          // E-mail контактного лица
 'url' => '',                   // Ссылка на найденного контрагента или контактное лицо
 'urlName' => '',               // Тип ссылки (company || contact)
 'companyResponsibleId' => 0    // Id ответственного за контрагента
]

sendPopupPhone(integer | array $user_id, string $name, string $to, string $from, string $status, interger $command_id = 0, string $url = «», interger $responsible = 0, string $pluginName = «»)

Отправить всплывающее уведомление о звонке пользователю.

Где:

user_id — id сотрудника, кому показать уведомление о звонке
name — Имя контрагента (контактного лица)
to — Телефон кому (номер телефона)
from — От кого (номер телефона)
status — «Connected» или «Disconnected»
command_id — уникальный id — это некий параметр который уходит во внешнюю систему и приходит
url — ссылка на найденного Контрагента
responsible — id Ответственного сотрудника за Контрагента
pluginName — Имя плагина — если не задать — выставиться автоматически

Метод ничего не возвращает.

addRelationship(string $phone, integer $direction, integer $companyId, integer contactId, string $contactEmail, integer $responsibleId, integer $callId, array $callsParams)

Создание контактов при звонке.

Где:

phone — Телефон
direction — Направление звонка
companyId — id Контрагента
contactId — id Контактного лица
contactEmail — E-mail контактного лица
responsibleId — id Ответственного за контрагента
callId — id Звонка
callsParams — Массив данных о звонке

Возвращает id созданного контакта.

addDeal(string $fromNumber, string $toNumber, integer $callId, array $callsParams, integer $direction)

Добавление информации в последнюю активную сделку контрагента, а также создание нового звонка.

Где:

fromNumber — Номер, с которого звонят
toNumber — Номер, на который звонят
callId — id Звонка
callsParams — Массив данных о звонке
direction — Направление звонка

Возвращает true | false, в зависимости от результата обновления информации в сделке.

addTask(string $name, integer $companyId, integer $callId, integer $responsibleId)

Добавление новой задачи.

Где:

name — Наименование задачи
companyId — id Контрагента
responsibleId— id Ответственного за задачу

Возвращает id созданной задачи.

addCompany(string $phone, string $name, …array $arrayFields)

Добавление новой контрагента.

Где:

phone — Телефон
name — Наименование контрагента
arrayFields — любое кол-во массивов или же одного массива со структурой [‘Имя поля’ => Значение поля]

Возвращает массив [‘id’ => ‘id Контрагента’, ‘name’ => ‘Наименование контрагента’].

Класс PluginSmsBase

PluginSmsBase — расширение класса PluginAction. От PluginSmsBase должны наследоваться все Sms Action.

Свойства:

Все свойства и методы PluginAction.

Методы:

actionSend()

Метод, который должен реализовать каждый sms плагин. Этот метод вызывается нашей системой для отправки SMS.

На вход идут две переменные:

text — сам текст
to — номер, куда отправляется сообщение

Для результата необходимо использовать resultSuccess() или resultError()

send($text, $phoneTo)

Метод, который должен реализовать каждый sms плагин. Это метод самой отправки. Именно он должен вызываться из actionSend().

Где:

text — сам текст
to — номер, куда отправляется сообщение

Отправка сообщений в программном коде системы вызывается следующим образом:

Kernel::getPluginsInstance()->getPlugin($pluginCode)->getAction(\Kernel\Plugins\PluginManager::PLUGIN_TYPE_SMS)->send($text, $phoneTo);

Где:

$text — текст сообщения, которое будет отправляться получателю
$phoneTo — номер получателя, на который будет отправляться сообщение
$pluginCode — название плагина, значение берётся из поля «Plugin code»

Также отправку сообщений можно реализовать посредством отправки Ajax-запроса на следующий адрес:

%crmUrl%/plugins/%pluginCode%/sms/send/

С передачей следующих POST-параметров:

text —текст сообщения
to — номер, куда отправляется сообщение

Класс PluginContentBase

PluginContentBase — расширение класса PluginAction. От PluginContentBase должны наследоваться все Content Action.

Свойства:

Все свойства и методы PluginAction.

Методы:

content()

Метод должен быть реализовать каждый content плагин. Возвращает html|text который встраивается в контент.

API Plugin

API plugin позволяет JavaScript получать и устанавливать настройки Плагина. Поддерживаемые форматы XML и JSON, в зависимости от ACCEPT заголовка.
API pligin работает по следующим ссылкам:

/plugins/%PluginName%/api/%MethodApi%

Методы:

getSettings — Возвращает все сохраненные настройки плагина.

/plugins/%PluginName%/api/getSettings

setSettings — установить настройки плагина. Имена ключей должны соответствовать ключам настроек манифеста и добавляться для POST запроса префикс object_ — например ключ плагина — key, то в POST должен быть object_key

/plugins/%PluginName%/api/setSettings

deletePlugin — удаление установленного плагина. Никаких параметров не надо. Удаляет со всеми настройками.

/plugins/%PluginName%/api/deletePlugin

installPlugin — установка нового плагина. Имена ключей должны соответствовать ключам настроек манифеста и добавляться для POST запроса префикс object_ — например ключ плагина — key, то в POST должен быть object_key

/plugins/%PluginName%/api/installPlugin

Структура папок плагина

Название папки/плагина — название компании или название выражающая суть плагина. Наименование должно быть уникально в рамках одной системы.

%plugin_name%
- actions — размещаются все %Type%Action
- css — для стилей
- html — для html шаблонов
- img — для всех изображений
  - logo_120.png — изображение в списке плагинов (120 x auto)
  - logo_200.png — изображение в описании плагина (200 x auto)
- js — для различных скриптов
- lang — содержатся все lang pack
  - ru.php — Возвращает ассоциативный массив.
- index.php — Основной файл плагина унаследованный от PluginBase
- manifest.php — Манифест. Описывает параметры плагина, указывает какие Actions использует, настройки, и права

Манифест — manifest.php

Это первый файл, с которого должны начинать разработку плагина.

<?php

/** Manifest plugin */

return [
    "name" => "%plugin_name%",
    "description" => "Plugin description ",
    "types" => [
        "phone"
        /*"content",*/ /*"sms",*/
    ],
    "vendor" => "vendor name",
    "version" => "1.0",
    "rating" => 0,
    "settings" => [
        "param1" => "",
        "param2",
    ],
    /*Для других плагинов*/
    "ActiveForms" => [
        "edit",
        "list",
    ],
];

Manifes.php возвращает ассоциативный массив:

name —- имя плагина
description — описание (может быть пустым)
types — Массив, в котором указываются, какие типы Action есть в этом плагине
vendor — Наименование разработчика
version — Версия плагина
rating — Рейтинг плагина (задается вручную)
settings — Настройки по умолчанию. Они же сохраняются в базу в установке и настройки плагина. Это ассоциативный массив ключ=>значение. Можно указать значения по умолчанию
ActiveForms — массив для Других плагинов(content). В массиве передается список типов форм для которых загружается

Класс Index(index.php) extends PluginBase

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

Свойства:

Все свойства и методы PluginBase.

Методы:

function getName() — должен возвращать всегда %PluginName%
actionIndex() — используется для вывода Описания. Вызывается, когда кликаешь в plugin manager на описание. Можно так же явно поучить контент по ссылке /plugins/%PluginName%/index
```
//print html/description.tpl file
public function actionIndex() {
     $this->display("description");
}
```

actionSettings() — используется для вывода Настроек. Вызывается при установки плагина и изменения его настроек.

Файл index.php метод actionSettings():

public function actionSettings() {
    //Если нужно установить переменные в шаблон,обязательно нужно вызвать этот метод и установить $this->page
    $this->beforeDisplay();
    //Все настройки mapping page
    $this->page->set($this->settings);

    //Установить Label с Langpack
    $this->page->set([
        "title_key" => $this->getRealName("title_key"),
    ]);
    //вывод шаблона settings.tpl
    $this->display("settings");
}

Файл html/settings.tpl:

<!-- Используется, если есть #include или [[css]] или [[js]] -->
{css static}
<link href="$app_path/css/#name.css" rel="stylesheet" media="all">
{/css}
{js static}
<script type="text/javascript" src="$app_path/js/#name.js"></script>
{/js}
<!-- Подключаем эти файлы если хотим использовать [[field]] [[CONTAINER]] -->
#include <fields>
#include <container>
<!-- Подключает css/style.css -->
[[css | name: style]]

[[CONTAINER | h: hide]]
    [[field | name: key | type: input | parentClass: w-100 | addLabel: $title_key$ | required:required-mode | value: $key$]]
[[CONTAINER_END]]

<!-- Подключает js/main.js -->
[[js | name: main]] 
</container></fields>

Языковой массив (Langpack)

Файлы языковых пакетов. Создаются в папке lang под именем (ru, en…). Например lang/ru.php. Файл должен возвращать массив ключ/значение.

<?php

 return [
    "company" => "Контрагент"
 ];
?>

Документация разработчика

Разработка плагинов

Класс PluginBase

Класс PluginAction

Свойства класса:

Класс PluginPhoneBase

actionCall()

actionInbound()

getShortNumber($user_id)

getAllUsersWithExtensions()

getCompanyByPhone($phone)

getContactByPhone($phone)

sendPopupPhone(integer | array $user_id, string $name, string $to, string $from, string $status, interger $command_id = 0, string $url = «», interger $responsible = 0, string $pluginName = «»)

addRelationship(string $phone, integer $direction, integer $companyId, integer contactId, string $contactEmail, integer $responsibleId, integer $callId, array $callsParams)

addDeal(string $fromNumber, string $toNumber, integer $callId, array $callsParams, integer $direction)

addTask(string $name, integer $companyId, integer $callId, integer $responsibleId)

addCompany(string $phone, string $name, …array $arrayFields)

Класс PluginSmsBase

Методы:

actionSend()

send($text, $phoneTo)

Класс PluginContentBase

Методы:

content()

API Plugin

Структура папок плагина

Манифест — manifest.php

Класс Index(index.php) extends PluginBase

Языковой массив (Langpack)

Оглавление

Не знаете с чего начать?