Плагин Roistat

Плагин предназначен для интеграции с маркетинговой платформой Roistat, которая позволяет управлять клиентами и сделками.

Механизм работы

Roistat предлагает периодическую синхронизацию сущностей. Плагин работает с 3 основными сущностями платформы:

Клиенты

  • Прототипом в ERP являются контрагенты. В рамках 1 контрагента может быть только 1 клиент. Группы контрагентов, которые могут быть зарегистрированы как клиенты можно настраивать в конфигурации плагина.

Сделки

  • Прототипом в ERP являются процессы. В рамках 1 процесса может быть только 1 сделка. Типы процессов, которые участвуют в сделках можно настраивать в конфигурации плагина.

Статусы сделок

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

В связи с этим производится хранение данных для синхронизации в собственных таблицах.

Обновление

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

Обновление будет происходить только в том случае, если изменились используемые в этих сущностях данные.

Синхронизация

Синхронизация данных происходит при помощи планировщика путём периодического запуска четырёх задач:

  • ru.bgcrm.plugin.roistat.client.task.UpdatedClientRegistrar;

  • ru.bgcrm.plugin.roistat.order.task.UpdatedOrderRegistrar;

  • ru.bgcrm.plugin.roistat.client.task.ErrorClientRegistrar;

  • ru.bgcrm.plugin.roistat.order.task.ErrorOrderRegistrar.

Вышеперечисленные задачи регистрируют сущности (клиентов и сделок) с заданным периодом, который можно указать в конфигурации:

scheduler.task.1.period=<period>

Где:

  • <period> - период между последовательным выполнением регистраций, в миллисекундах. По умолчанию 500.

Задачи UpdatedClientRegistrar и UpdatedOrderRegistrar отвечают за поиск обновлённых клиентов (сделок) и регистрацию их в системе Roistat. Выполнение задачи прекращается, если не будет найден клиент (сделка) для регистрации.

Для регистрации сделки обязательно наличие зарегистрированного клиента и статуса сделки в системе Roistat.

Если при регистрации возникает ошибка, то сущность не будет зарегистрирована и получает статус ошибки. Задачи ErrorClientRegistrar и ErrorOrderRegistrar отвечают за поиск ошибочных клиентов (сделок) и повторную регистрацию их в системе Roistat. Поиск ошибочных клиентов (сделок) осуществляется с проверкой, для определения, прошёл ли достаточный промежуток времени с момента последней попытки синхронизации. Промежуток для этих задач указывается в конфигурации:

scheduler.task.1.syncInterval=<syncInterval>

Где:

  • <syncInterval> - промежуток времени в часах, который должен пройти с последней попытки синхронизации сущности с ошибкой. По умолчанию 1.

Для синхронизации статусов сделок имеется задача:

  • ru.bgcrm.plugin.roistat.order.status.task.OrderStatusRegistrar.

Задача извлекает все статусы, прописанные в конфигурации и регистрирует их в системе Roistat.

Конфигурация плагина Roistat

Общая конфигурация

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

plugin.roistat.enabled=<enabled>
plugin.roistat.project=<project>

Где:

  • <enabled> - логическое значение, по умолчанию false;

  • <project> - номер проекта в системе Roistat.

Конфигурация клиентов

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

plugin.roistat.client.customer.groups=<customerGroups>

Где:

  • <customerGroups> - идентификаторы групп контрагентов, через запятую. Если не указано, любой контрагент может быть зарегистрирован, как клиент в Roistat.

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

plugin.roistat.client.details.provider=<clientDetailsProvider>

Где:

  • <clientDetailsProvider> - класс-провайдер формирования деталей клиента, по умолчанию ru.bgcrm.plugin.roistat.client.provider.impl.CommonClientDetailsProvider.

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

plugin.roistat.client.details.common.customer.phone=<phone>
plugin.roistat.client.details.common.customer.email=<email>
plugin.roistat.client.details.common.customer.company=<company>
plugin.roistat.client.details.common.customer.birthDate=<birthDate>
plugin.roistat.client.details.common.customer.fields.<field>=<paramId>

Где:

  • <phone> - числовой идентификатор параметра ERP типа phone;

  • <email> - числовой идентификатор параметра ERP типа email;

  • <company> - числовой идентификатор параметра ERP типа text;

  • <birthDate> - числовой идентификатор параметра ERP типа date;

  • <field> - наименование дополнительного поля;

  • <paramId> - числовой идентификатор параметра ERP для дополнительного поля.

Для создания провайдера с желаемой логикой, необходимо создать класс реализующий интерфейс ru.bgcrm.plugin.roistat.client.provider.ClientDetailsProvider

Конфигурация сделок

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

plugin.roistat.order.process.types=<processTypes>

Где:

  • <processTypes> - идентификаторы типов процессов, через запятую.

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

plugin.roistat.order.details.provider=<processDetailsProvider>

Где:

  • <processDetailsProvider> - класс-провайдер формирования деталей сделки. Обязательное значение в случае использования типа процесса в сделках.

Для создания провайдера с желаемой логикой, необходимо создать класс реализующий интерфейс ru.bgcrm.plugin.roistat.order.details.OrderDetailsProvider

Конфигурация статусов сделок

plugin.roistat.status.<n>.id=<id>
plugin.roistat.status.<n>.title=<title>
plugin.roistat.status.<n>.type=<type>

Где:

  • <n> - порядковый номер записи;

  • <id> - идентификатор статуса, в случае отсутствия значения, конфигурация данного статуса игнорируется;

  • <title> - наименование статуса, в случае отсутствия значения, конфигурация данного статуса игнорируется;

  • <type> - тип статуса в системе Roistat, в случае отсутствия или указания недопустимого значения, подставляется значение по умолчанию - progress. Статус соответствует одной из трёх групп:

    • progress - группа В работе;

    • paid - группа Оплаченные;

    • canceled - группа Отмененные.