Репозиторий с шаблоном разработки «Правила интеграции с внешними системами».
Решение предоставляет механизм настройки правил интеграции для импорта данных по расписанию и в определенном порядке.
Состав объектов разработки:
- фоновый процесс «Выполнить интеграцию с внешней системой»;
- справочник «Настройки интеграции» (IntegrationSetting);
- абстрактный справочник «Базовое правило интеграции» (IntegrationRuleBase);
- абстрактный справочник «Базовое правило импорта» (ImportRuleBase);
- справочник «Правило импорта подразделений» (ImportRuleDepartment);
- справочник «Правило импорта сотрудников» (ImportRuleEmployee);
- справочник «Правило импорта должностей» (ImportRuleJobTitle);
В справочнике «Настройки интеграции» можно задать общие для нескольких правил параметры для подключения к внешней системе (логин, пароль, адрес, таймаут), список правил импорта для этой системы и порядок их выполнения.
В справочниках правил задаются параметры запроса и параметры для подключения к внешней системе (логин, пароль, адрес, таймаут). В первую очередь используются параметры подключения, заданные в правиле. Если в правиле они не заданы, то используются параметры из справочника «Настройки интеграции».
Фоновый процесс по расписанию получает все действующие настройки и выполняет импорт из внешней системы по порядку из настройки. Результаты импорта отправляются ответственным.
Note
В шаблоне реализован пример импорта в Directum RX справочников Подразделения, Должности и Сотрудники.
Note
Замечания и пожеланию по развитию шаблона разработки фиксируйте через Issues. При оформлении ошибки опишите сценарий для воспроизведения. Для пожеланий приведите обоснование для описываемых изменений - частоту использования, бизнес-ценность, риски и/или эффект от реализации.
Внимание! Изменения будут вноситься только в новые версии.
Существуют следующие варианты расширения:
- добавление нового типа коннектора;
- создание или изменение правила интеграции;
- вызов интеграции из событий сущностей, блоков задач, действий и т.д.
Тип коннектора - это элемент перечисления, который указывается в справочнике настроек интеграции и используется для выбора подходящего обработчика правил интеграции.
Правило интеграции представляет собой тип справочника с набором прикладных функций. Правило отправляет запрос из одной системы в другую и обрабатывает полученный ответ.
В шаблоне предполагается, что внешняя система возвращает ответ в виде двумерного массива (матрицы), в котором колонки соответствуют параметрам, а строки – значениям параметров.
В среде разработки Directum RX после установки решения IntegrationRulesSolution появляется модуль Integration с набором правил.
В качестве примера рассмотрим тип коннектора, который имитирует обмен данными с внешней системой без подключения к ней.
- Перекройте справочник Настройки интеграции (IntegrationSetting).
- Типы коннекторов задаются в справочнике Настройки интеграции (IntegrationSetting) в свойстве ConnectorType. Добавьте значение перечисления, которое соответствует новому типу коннектора, например DummyConnector.
- Переопределите серверную функцию ExecuteConnector() в правиле интеграции и добавьте обработку нового типа коннектора:
/// <summary>
/// Выполнить обращение к внешней системе.
/// </summary>
/// <param name="parameters">Словарь параметров.</param>
/// <param name="connectorType">Тип коннектора подключения.</param>
/// <param name="logs">Структурированный лог.</param>
/// <returns>Матрица с ответом от внешней системы.</returns>
public override List<System.Collections.Generic.Dictionary<string, string>> ExecuteConnector(DirRX.Integration.IIntegrationRuleBase rule, System.Collections.Generic.Dictionary<string, string> parameters, List<DirRX.Integration.Structures.Module.LogStruct> logs)
{
var response = new List<Dictionary<string, string>>();
if (_obj.ConnectorType == DirRX.Dummy.IntegrationSetting.ConnectorType.DummyConnector)
response = this.ExecuteDummyConnector(rule, parameters, logs);
else
response = base.ExecuteConnector(rule, parameters, logs);
return response;
}
- Создайте функции для имитации обращения к внешней системе ExecuteDummyConnector (по аналогии ExecuteDefaultConnector), формирования запроса SendGetDepartmentsRequest (по аналогии SendDefaultRequest) и разбора ответа ParseDepartmentsResponse (по аналогии ParseDefaultResponse).
/// <summary>
/// Имитация работы с внешней системой.
/// </summary>
/// <param name="rule">Правило интеграции.</param>
/// <param name="parameters">Словарь параметров.</param>
/// <param name="logs">Структурированный лог.</param>
/// <returns>Матрица с ответом от внешней системы.</returns>
public virtual List<System.Collections.Generic.Dictionary<string, string>> ExecuteDummyConnector(DirRX.Integration.IIntegrationRuleBase rule, System.Collections.Generic.Dictionary<string, string> parameters, List<DirRX.Integration.Structures.Module.LogStruct> logs)
{
var result = new List<Dictionary<string, string>>();
var response = string.Empty;
#region Заполнение данных в матрице ответа от внешней системы («заглушка»).
if (parameters["method"] != null)
{
if (parameters["method"] == "GetDepartments")
{
response = SendGetDepartmentsRequest();
if (!string.IsNullOrEmpty(response))
result = ParseDepartmentsResponse(response);
}
}
#endregion
return result;
}
/// <summary>
/// Выполняет отправку запроса подразделений и возвращает ответ.
/// </summary>
public static string SendGetDepartmentsRequest()
{
// http запрос к веб-сервису, sql запрос к БД, загрузка из файла.
}
/// <summary>
/// Выполнить обработку строки с ответом и преобразовать в структурированный формат.
/// </summary>
/// <param name="response">Строка, содержащая ответ.</param>
/// <returns>Ответ в виде списка массивов строк.</returns>
public virtual List<System.Collections.Generic.Dictionary<string, string>> ParseDepartmentsResponse(string response)
{
var result = new List<Dictionary<string, string>>();
// Разбор ответа.
return result;
}
- Опубликуйте решение и проверьте внесенные изменения.
- В веб-клиенте Directum RX в записи справочника Настройки синхронизации с внешней системой в раскрывающемся списке Тип коннектора выберите пункт с добавленным коннектором. Затем укажите остальные настройки синхронизации и проверьте ее работоспособность.
Схема наследования правил:
Если нужно реализовать запросы к внешней системе из Directum RX, создайте правило интеграции. При этом в качестве базового правила используйте IntegrationRuleBase. Чтобы реализовать импорт новой сущности в Directum RX, создайте правило, в качестве базового правила используйте ImportRuleBase. Если требуется изменить правило импорта подразделений, должностей или сотрудников, то перекройте нужное правило, например ImportRuleDepartment, и переопределите его функции.
Общий порядок создания правила импорта:
- В своем решении создайте наследника от базового правила ImportRuleBase.
- Переопределите серверные функции базового правила с учетом решаемой задачи:
- SaveData() – сохранение полученных данных в Directum RX;
- ParseResponseItem() – обработка строки матрицы с ответом от внешней системы.
- Создайте серверную функцию, например ImportEntities(), которая импортирует данные в сущность Directum RX. Создайте структуру, которая содержит набор полей сущности. Созданная функция импорта будет вызываться из функции SaveData().
- Переопределите функцию инициализации, чтобы при ее выполнении выдавались права доступа на новые правила.
- Создайте правило для импорта контрагентов ImportRuleCounterparty. В качестве базового правила укажите ImportRuleBase.
- В созданном правиле ImportRuleCounterparty создайте структуру CounterpartyStructure, которая содержит набор полей сущности.
/// <summary>
/// Структура для работы с контрагентами.
/// </summary
partial class CounterpartyStructure
{
public string Name { get; set; }
public string Tin { get; set; }
public string Psrn { get; set; }
}
- Переопределите серверную функцию SaveData() базового правила.
/// <summary>
/// Сохранение полученных данных в Directum RX.
/// </summary>
/// <param name="response">Матрица с ответом от внешней системы.</param>
/// <param name="logs">Структурированный лог.</param>
public override void SaveData(List<string[]> response, List<DirRX.Solution.Structures.Module.LogStruct> logs)
{
var entities = new List<DirRX.Solution.Structures.ImportRuleCounterparty.CounterpartyStructure>();
foreach (var responseItem in response)
entities.Add(ParseResponseItem(responseItem));
if (entities.Any())
{
ImportEntities(entities, logs);
}
}
- Переопределите серверную функцию ParseResponseItem() базового правила.
/// <summary>
/// Обработка строки матрицы с ответом от внешней системы.
/// </summary>
/// <param name="responseItem">Строка матрицы с ответом от внешней системы.</param>
/// <returns>Свойства сущности в структурированном виде.</returns>
public virtual DirRX.Solution.Structures.ImportRuleCounterparty.CounterpartyStructure ParseResponseItem(string[] responseItem)
{
var entity = new
DirRX.Solution.Structures.ImportRuleCounterparty.CounterpartyStructure();
entity.Name = responseItem[0];
entity.Tin = responseItem[1];
entity.Psrn = responseItem[2];
return entity;
}
- Создайте серверную функцию импорта контрагентов.
/// <summary>
/// Импорт контрагентов.
/// </summary>
/// <param name="items">Структурированный набор данных.</param>
/// <returns>Список структурированных логов.</returns>
[Remote]
public virtual void ImportEntities(List<DirRX.Solution.Structures.ImportRuleCounterparty.CounterpartyStructure > items, List<DirRX.Solution.Structures.Module.LogStruct> logs)
{
foreach (var item in items)
{
var counterparty = Sungero.Parties.Counterparties.Create();
counterparty.Name = item.Name;
counterparty.TIN = item.Tin;
counterparty.PSRN = item.Psrn;
counterparty.Save();
}
}
- Переопределите функцию инициализации модуля Integration. При инициализации необходимо выдать права на новый справочник правил интеграции.
/// <summary>
/// Выдача прав на справочники, соответствующие правилам.
/// </summary>
public override void GrantRightsOnDatabooks()
{
base.GrantRightsOnDatabooks();
var allUsers = Roles.AllUsers;
if (allUsers != null)
{
DirRX.Solution.ImportRuleCounterparties.AccessRights.Grant(allUsers, DefaultAccessRightsTypes.Read);
DirRX.Solution.ImportRuleCounterparties.AccessRights.Save();
}
}
Общий порядок изменения стандартных правил ImportRuleEmployees, ImportRuleDepartments, ImportRuleJobtitles:
- В своем решении перекройте необходимое правило.
- Реализуйте новую структуру для хранения данных, полученных из внешней системы, если набор получаемых полей отличается от существующей структуры.
- В зависимости от поставленной задачи создайте новые функции или переопределите существующие функции правил:
- SaveData() – сохранение полученных данных в Directum RX;
- ParseResponseItem() – обработка строки матрицы с ответом от внешней системы;
- ImportEntities() – импорт сущности.
- Переопределите соответствующую функцию импорта данных в сущность Directum RX. Если импорт будет выполняться в новую сущность, создайте новую функцию импорта.
Для работы требуется установленный Directum RX версии 4.12 и выше.
- Склонировать репозиторий с rx-template-integration-rules в папку.
- Указать в config.yml в разделе DevelopmentStudio:
GIT_ROOT_DIRECTORY: '<Папка из п.2>'
REPOSITORIES:
repository:
- '@folderName': 'work'
'@solutionType': 'Work'
'@url': https://github.com/DirectumCompany/rx-template-integration-rules'
- '@folderName': 'base'
'@solutionType': 'Base'
'@url': ''Возможные варианты
A. Fork репозитория
- Сделать fork репозитория rx-template-integration-rules для своей учетной записи.
- Склонировать созданный в п. 1 репозиторий в папку.
- Указать в config.yml в разделе DevelopmentStudio:
GIT_ROOT_DIRECTORY: '<Папка из п.2>'
REPOSITORIES:
repository:
- '@folderName': 'work'
'@solutionType': 'Work'
'@url': https://github.com/<Учетная запись>/rx-template-integration-rules'
- '@folderName': 'base'
'@solutionType': 'Base'
'@url': ''B. Подключение на базовый слой.
Вариант не рекомендуется, так как при выходе версии шаблона разработки не гарантируется обратная совместимость.
- Склонировать репозиторий rx-template-integration-rules в папку.
- Указать в config.yml в разделе DevelopmentStudio:
GIT_ROOT_DIRECTORY: '<Папка из п.1>'
REPOSITORIES:
repository:
- '@folderName': 'work'
'@solutionType': 'Work'
'@url': '<Адрес репозитория для рабочего слоя>'
- '@folderName': 'base'
'@solutionType': 'Base'
'@url': ''
- '@folderName': 'base'
'@solutionType': 'Base'
'@url': 'https://github.com/DirectumCompany/rx-template-integration-rules'C. Копирование репозитория в систему контроля версий.
Рекомендуемый вариант для проектов внедрения.
- В системе контроля версий с поддержкой git создать новый репозиторий.
- Склонировать репозиторий <Название репозитория> в папку с ключом
--mirror. - Перейти в папку из п. 2.
- Импортировать клонированный репозиторий в систему контроля версий командой:
git push –mirror <Адрес репозитория из п. 1>