Sync Engine — механизм синхронизации Creatio с внешними хранилищами данных. Внешнее хранилище — внешний сервис или приложение, данные из которого синхронизируются с Creatio.
Назначение Sync Engine:
- Импорт данных из внешних хранилищ. Подразумевает создание, изменение и удаление Entity в приложении на основе полученных данных.
- Экспорт данных во внешние хранилища.
Классы механизма синхронизации
Классы, которые реализуют логику работы механизма синхронизации Sync Engine:
- Terrasoft.Sync.SyncAgent — агент синхронизации. Метод Synchronize() класса SyncAgent запускает синхронизацию между указанными хранилищами данных.
- Terrasoft.Sync.SyncContext — контекст синхронизации. Представляет собой агрегацию провайдеров и метаданных для работы класса SyncAgent.
- Terrasoft.Sync.LocalProvider — работа с хранилищем Creatio. Позволяет работать с классом LocalItem.
- Terrasoft.Sync.LocalItem — элемент синхронизации из хранилища Creatio. Представляет собой один или несколько объектов Creatio, которые, как одно целое, синхронизируются с внешним хранилищем. Элемент синхронизации из внешнего хранилища, который конвертирован в сущность LocalItem. Содержит набор экземпляров класса SyncEntity.
- Terrasoft.Sync.RemoteProvider — работа с внешним хранилищем.
- Terrasoft.Sync.RemoteItem — элемент синхронизации внешнего хранилища. Представляет собой набор данных из внешнего хранилища, который синхронизируется атомарно. Может состоять из одной или нескольких сущностей (записей) внешнего хранилища.
- Terrasoft.Sync.SyncEntity — элемент синхронизации Creatio. Является оберткой над отдельными Entity. Позволяет работать с Entity, как с синхронизируемым объектом. Задает состояние и действие (добавить, удалить, изменить), которое необходимо выполнить с Entity.
Служебная информация синхронизированных элементов содержится в таблице [SysSyncMetaData] базы данных. По сути, таблица разграничивает синхронизацию из хранилищ Creatio и внешних хранилищ. Таблица может содержать несколько записей для одного элемента синхронизации — по одной для каждого объекта приложения, который включен в элемент синхронизации.
Метаданные для одного элемента синхронизации в приложении представлены объектом класса ItemMetadata (коллекция элементов из таблицы [SysSyncMetaData]). Управление метаданными осуществляется через класс, который реализует интерфейс IReplicaMetadata. Экземпляр класса создается для конкретного хранилища через класс-фабрику MetaDataStore.
Алгоритм выполнения синхронизации
-
Синхронизируйте измененные элементы.
- Создайте экземпляр класса SyncAgent.
- Создайте контекст синхронизации SyncContext.
- Актуализируйте записи в таблице метаданных [SysSyncMetaData] данными из Creatio. Для этого вызовите метод CollectChangesInSyncedEntities() класса ReplicaMetadata, который реализует интерфейс IReplicaMetadata. В процессе актуализации записей возможны различные варианты актуализации записей.
После этого запускается синхронизация хранилищ.
Действия, которые выполняются во время синхронизации хранилищ:
- Поочередно запрашиваются все изменения из внешнего хранилища.
- Запрашиваются метаданные для каждого элемента внешнего хранилища.
В процессе синхронизации хранилищ возможны различные варианты.
-
Синхронизируйте новые элементы.
- В Creatio получите элементы, которые были изменены между прошлой синхронизацией и началом текущей синхронизации.
- Примените изменения во внешнем хранилище.
- Обновите дату модификации элементов в метаданных (источник изменения Creatio).
- Во внешнее хранилище добавьте новые, еще не синхронизированные записи из Creatio.
- Для новых элементов добавьте метаданные.
Варианты актуализации записей:
-
После последней синхронизации в Creatio изменена ранее синхронизированная сущность:
- В метаданных соответствующей записи изменяется дата модификации.
- В колонку [LocalState] таблицы [SysSyncMetaData] устанавливается значение "Изменен".
- В качестве источника модификации устанавливается идентификатор LocalStore.
- После последней синхронизации в Creatio удалена синхронизируемая сущность. В этом случае в колонку [LocalState] соответствующей записи таблицы [SysSyncMetaData] устанавливается значение "Удален".
- Для синхронизируемой сущности в Creatio отсутствует соответствующая запись в таблице [SysSyncMetaData]. В этом случае сущность игнорируется.
Варианты синхронизации хранилищ:
-
Не удалось получить метаданные (синхронизируемый элемент является новым).
- Элемент конвертируется в элемент Creatio. Для заполнения объекта синхронизации у конкретного экземпляра RemoteItem приложения вызывается метод FillLocalItem().
- Запись сохраняется в метаданных. При сохранении в таблице [SysSyncMetaData] указываются идентификаторы внешнего хранилища и элемента во внешнем хранилище, в качестве даты создания и даты модификации устанавливается текущая дата, в качестве источника создания и источника модификации устанавливается внешнее хранилище.
- Метаданные получены (синхронизируемый элемент уже синхронизирован с Creatio) В этом случае выполняется переход к решению конфликта версий. По умолчанию приоритет имеют последние изменения в приложении или внешнем хранилище (реализация содержится в классе RemoteProvider).
- Актуализируются метаданные для текущей пары элементов синхронизации.
Пример выполнения синхронизации
Рассмотрим работу синхронизации на примере активности и ее участников, которые синхронизируются в одну задачу Google-календаря.
Схема выполнения синхронизации представлена на рисунке ниже.
LocalItem — элемент синхронизации, который содержит активность (объект Activity) и ее участников (коллекция объектов SyncEntity). Представляет собой коллекцию объектов (SyncEntity), в которые конвертируется задача Google.
RemoteItem — задача Google, которую получило приложение Creatio от внешней системы.
Несмотря на то, что активность и ее участники — один элемент синхронизации, в метаданных содержатся одна запись для активности и по одной записи для каждого участника.
Creatio предоставляет возможность преобразования одного внешнего объекта в несколько локальных объектов Creatio. Не поддерживается преобразование нескольких внешних объектов в несколько локальных объектов, когда этот набор является одним элементом синхронизации.
Пространство имен Terrasoft.Sync.
Класс Terrasoft.Sync.SyncAgent реализует агент синхронизации. Позволяет синхронизировать данные между хранилищем Creatio и внешним хранилищем. Агент не решает конфликты синхронизации при их обнаружении. При обнаружении конфликта синхронизации агент перенаправляет его в IConflictResolver, который возвращает объект SyncConflictResolution. На основе этого объекта агент выполняет необходимые действия.
Конструкторы
Создает экземпляр агента синхронизации.
userConnection | Пользовательское подключение. |
localProvider | Хранилище Creatio. |
remoteProvider | Внешнее хранилище. |
Контекст синхронизации.
syncContext | Контекст синхронизации. |
Пространство имен Terrasoft.Sync.
Класс Terrasoft.Sync.SyncContext реализует контекст синхронизации. Представляет собой агрегацию провайдеров и метаданных для работы класса SyncAgent.
Свойства
Объект, который позволяет сохранять сообщения в лог интеграции.
Логгер сообщений для механизма синхронизации.
Объект, который позволяет получить или применить изменения в хранилище Creatio. Позволяет работать с LocalItem.
Объект, который позволяет получить или применить изменения во внешнем хранилище.
Пользовательское подключение.
Дата и время последней синхронизации (UTC).
Текущие дата и время синхронизации (UTC). Устанавливается после обновления метаданных.
Методы
Устанавливает значение колонки поиска сущности.
entity | Экземпляр класса Terrasoft.Core.Entities.Entity. |
lookupColumnName | Имя справочной колонки. |
lookupDisplayValue | Отображаемое значение справочной колонки. |
Устанавливает значение колонки поиска сущности.
entity | Экземпляр класса Terrasoft.Core.Entities.Entity. |
lookupColumnName | Имя справочной колонки. |
lookupDisplayValue | Отображаемое значение справочной колонки. |
lookupDisplayColumnName | Отображаемое имя справочной колонки. |
Записывает в журнал информационное сообщение.
operation | Действие объекта синхронизации. |
direction | Направление синхронизации. |
format | Формат. |
args | Параметры формата. |
Записывает в журнал сообщение об ошибке.
operation | Действие объекта синхронизации. |
direction | Направление синхронизации. |
format | Формат. |
args | Параметры формата. |
Записывает в журнал сообщение об ошибке.
operation | Действие объекта синхронизации. |
direction | Направление синхронизации. |
format | Формат. |
exception | Исключение элемента, который вызвал ошибку. |
args | Параметры формата. |
Пространство имен Terrasoft.Sync.
Класс Terrasoft.Sync.LocalProvider реализует работу с локальным хранилищем. Позволяет работать с классом LocalItem.
Конструкторы
Создает экземпляр класса с помощью UserConnection.
userConnection | Пользовательское подключение. |
Свойства
Идентификатор хранилища Creatio, которое будет синхронизировано.
Экземпляр UserConnection.
Максимальное количество элементов в выборке.
Методы
Добавляет в EntitySchemaQuery-запрос указанные колонки.
esqForFetching | Экземпляр класса EntitySchemaQuery. |
entityConfig | Экземпляр класса EntityConfig. |
Применяет изменения к каждому экземпляру сущности в коллекции entities.
context | Экземпляр класса SyncContext. |
entities | Экземпляр класса LocalItem. |
Загружает коллекцию сущностей, которые связаны с конкретным элементом синхронизации.
itemMetaData | Экземпляр класса ItemMetadata. |
itemSchema | Экземпляр класса SyncItemSchema. |
loadAllColumns | Если установлено значение true, то загружаются все столбцы сущностей. При значении false загружаются только столбцы из экземпляра сущности EntityConfig. |
Пространство имен Terrasoft.Sync.
Класс Terrasoft.Sync.LocalItem реализует элемент синхронизации из хранилища Creatio. Представляет собой один или несколько объектов Creatio, которые, как одно целое, синхронизируются с внешним хранилищем. Элемент синхронизации из внешнего хранилища, который конвертирован в сущность LocalItem, содержит набор экземпляров класса SyncEntity.
Свойства
Коллекция SyncEntity, которая ставится в соответствия с одним SyncItem. Содержит коллекцию пар "ключ-значение", где ключ — имя схемы, а значение — коллекция SyncEntity этой схемы.
Наибольшее значение даты и времени модификации из всех Entities в LocalItem.
Схема настройки сущности элемента синхронизации.
Методы
Добавляет новый SyncEntity в коллекцию. Если SyncEntity с таким EntityId уже существует, заменяет его.
schemaName | Имя схемы. |
syncEntity | Синхронизируемая сущность. |
Создает и добавляет новый SyncEntity в коллекцию.
userConnection | Пользовательское подключение. |
schemaName | Имя схемы. |
Создает счетчик SyncEntity.
Пространство имен Terrasoft.Sync.
Класс Terrasoft.Sync.RemoteProvider реализует работу с внешним хранилищем.
Свойства
Идентификатор внешнего хранилища, с которым будет выполняться синхронизация.
Дата и время последней синхронизации.
Количество элементов, которые импортированы из внешнего хранилища.
Количество элементов, которые импортированы из хранилища Creatio.
Настройка коллекции схем внешнего хранилища.
Флаг, который позволяет использовать метаданные.
Информация о сессии пользователя.
Методы
Применяет изменения в элементе внешнего хранилища.
context | Экземпляр класса SyncContext. |
syncItem | Элемент синхронизации. |
Вызывается после обработки изменений во внешнем хранилище и хранилище Creatio. Предназначен для реализации дополнительных действий для конкретной реализации интеграции.
context | Экземпляр класса SyncContext. |
Возвращает перечень новых элементов для синхронизации внешнего хранилища.
context | Экземпляр класса SyncContext. |
Возвращает перечень элементов для синхронизации внешнего хранилища.
context | Экземпляр класса SyncContext. |
Возвращает объект синхронизации из внешнего хранилища по уникальному внешнему ключу.
schema | Схема синхронизации. |
id | Уникальный внешний ключ. |
Для текущего элемента возвращает удаленный синхронизированный элемент.
schema | Схема синхронизации. |
Получает типы всех элементов синхронизации из внешнего хранилища. Возвращает коллекцию всех типов, которые реализуют интерфейс IRemoteItem. На их основе, SyncAgent строит экземпляры SyncItemSchema, которые описывают синхронизируемые сущности.
Возвращает количество элементов, которые необходимо обработать на одной странице приложения Creatio.
context | Экземпляр класса SyncContext. |
Возвращает объект синхронизации по значению метаданных.
schema | Схема синхронизации. |
itemMetadata | Метаданные синхронизации. |
Разрешает конфликт между измененными элементами хранилища Creatio и внешнего хранилища. По умолчанию приоритет имеют изменения в Creatio.
syncItem | Элемент синхронизации. |
itemMetadata | Метаданные синхронизации. |
localStoreId | Идентификатор хранилища Creatio. |
Забирает элемент синхронизации из внешнего хранилища.
remoteItem | Элемент синхронизации. |
Возвращает флаг, который устанавливает необходимость актуализации метаданных.
Возвращает элементы синхронизации, которые были изменены в хранилище Creatio после последней синхронизации.
context | Экземпляр класса SyncContext. |
modifiedItemsEsq | Запрос к объекту схемы. |
Записывает в журнал сообщение об ошибке.
format | Формат строки с сообщением об ошибке. |
exception | Исключение, которое вызвало ошибку. |
args | Параметры сообщения об ошибке. |
Пространство имен Terrasoft.Sync.
Класс Terrasoft.Sync.RemoteItem реализует интерфейс IRemoteItem. Интерфейс реализует элемент синхронизации внешнего хранилища. Представляет собой набор данных из внешнего хранилища, который синхронизируется атомарно. Может состоять из одной или нескольких сущностей (записей) внешнего хранилища. Класс RemoteItem является контейнером для данных, которые приходят из внешнего хранилища. Также класс преобразовывает эти данные в сущности Entity, и наоборот — из Entity наполняет внешнее хранилище.
Свойства
Идентификатор элемента во внешнем хранилище.
Версия элемента в текущем хранилище (дата последней модификации). Используется для сравнения двух элементов из разных хранилищ.
Описывает схему соответствия синхронизируемого элемента.
Действие, которые выполнено над элементом с даты последней синхронизации.
Действие, которое необходимо выполнить над элементом.
Методы
Заполняет свойства элемента LocalItem хранилища Creatio значениями элемента внешнего хранилища. Используется для применения изменений в хранилище Creatio.
context | Экземпляр класса SyncContext. |
localItem | Элемент хранилища Creatio, который соответствует текущему элементу внешнего хранилища. |
Заполняет свойства элемента внешнего хранилища значениями из элемента LocalItem хранилища Creatio. Используется для применения изменений во внешнем хранилище.
context | Экземпляр класса SyncContext. |
localItem | Элемент хранилища Creatio, который соответствует текущему элементу внешнего хранилища. |
Пространство имен Terrasoft.Sync.
Класс Terrasoft.Sync.SyncEntity реализует элемент синхронизации Creatio. Является оберткой над отдельными Entity. Позволяет работать с Entity, как из синхронизируемым объектом. Задает состояние и действие (добавить, удалить, изменить), которое необходимо выполнить с Entity.
Конструкторы
Создает экземпляр элемента синхронизации.
entity | Экземпляр класса Entity. |
state | Экземпляр класса SyncState. |
Свойства
Идентификатор сущности.
Имя схемы, для которой создается обертка.
Сущность, для которой создается обертка.
Последнее действие, которое выполнено над сущностью.
Действие, которое необходимо выполнить из сущностью.
Дополнительная информация, которая связана с конкретной сущностью. Внешний провайдер для пользовательских потребностей.
Пространство имен Terrasoft.Sync.
Класс Terrasoft.Sync.SyncItemSchema задает схему настройки сущности элемента синхронизации.
Свойства
Название типа сущности.
Тип сущности.
Настройка основной сущности элемента синхронизации.
Список настроек сущностей элемента синхронизации.
Список настроек сущностей деталей элемента синхронизации.
Определяет направление синхронизации для объектов текущего типа. По умолчанию — DownloadAndUpload. Если не содержит флаг Download, то изменения не будут применяться в Creatio. Если не содержит флаг Upload, то не будут выбираться новые сущности из Creatio.
Методы
Создает настройки сущности элемента синхронизации со всеми настройками связанных сущностей.
syncValueType | Тип сущности. |
Проверяет правильность сформированного EntityConfig. Если проверка не прошла, то выдается исключение (если в EntityConfig имя схемы указано два раза, то генерируется DublicateDataException. Если указано имя несуществующей схемы, то генерируется InvalidSyncItemSchemaException).
userConnection | Пользовательское подключение. |
Пространство имен Terrasoft.Sync.
Атрибутом Map декорируются реализации интерфейса IRemoteItem.
Конструкторы
Указывает порядок сохранения сущностей в хранилище Creatio из указанной схемы.
schemaName | Имя схемы, которая участвует в текущем элементе синхронизации. |
order | Порядок сохранения сущностей в хранилище Creatio. |
В таком объявлении класса задача из Google-календаря синхронизируется с активностью и участниками активности из Creatio. Активность (объект Activity) указывается первой, поскольку участники активности (объект ActivityParticipant) хранит ссылку на создаваемую активность и при другом порядке будет вызвано исключение.
В большинстве случаев класс SyncAgent может автоматически сформировать запрос по выборке новых элементов синхронизации из Creatio. Для этого необходимо указать основную сущность и способ связи с деталями.
Пример указания основной сущности и способа связи с деталями представлен ниже.
В данном случае в базу данных отправится один запрос на получение новых активностей и по одному запросу на каждую выбранную активность для получения связанных с ней участников.
Свойства
Имя схемы объекта в хранилище Creatio.
Порядок обработки сущности для элемента синхронизации. Чем меньше значение, тем раньше сущность будет обработана при обработке элемента синхронизации.
Определяет направление синхронизации для объектов текущего типа. По умолчанию — DownloadAndUpload. Если не содержит флаг Download, то изменения не будут применять в Creatio. Если не содержит флаг Upload, то не будут выбираться новые сущности из Creatio.
Имя схемы главного объекта. Не может указываться в паре с IsPrimarySchema.
Имя колонки для связи детали с главным объектом. Не может указываться в паре с IsPrimarySchema.
Флаг, который указывает, что данная схема является основной в данном элементе синхронизации. Может быть установлен только для одной схемы.
Названия колонок, которые будут загружаться из хранилища Creatio. Если значение не указано, то загружаются все колонки объекта.
Пространство имен Terrasoft.Sync.
Класс Terrasoft.Sync.EntityConfig настраивает сущность элемента синхронизации.
Свойства
Название схемы объекта сущности.
Порядок обработки сущности для элемента синхронизации. Чем меньше значение, тем раньше сущность будет обработана при обработке элемента синхронизации.
Доступные направления для синхронизации. По умолчанию — DownloadAndUpload. Если не содержит флаг Download, то изменения не будут применяться в Creatio. Если не содержит флаг Upload, то не будут выбираться новые сущности из Creatio.
Названия колонок, которые будут загружаться из хранилища Creatio. Если при создании экземпляра значение не указано, то загружаются все колонки объекта.
Пространство имен Terrasoft.Sync.
Класс-фабрика Terrasoft.Sync.MetaDataStore создает конкретный экземпляр класса, который реализует интерфейс IReplicaMetadata для хранилища.
Пространство имен Terrasoft.Sync.
Класс Terrasoft.Sync.ItemMetadata является неделимым объектом метаданных синхронизации. Содержит набор метаданных для каждой сущности синхронизации (коллекция элементов SysSyncMetadata).
Пространство имен Terrasoft.Sync.
Класс Terrasoft.Sync.ReplicaMetadata реализует интерфейс IReplicaMetadata, инкапсулирует метаданные синхронизации.
Методы
Поскольку методы класса ReplicaMetadata совпадают с методами интерфейса IReplicaMetadata, ознакомиться с описанием методов можно в статье Интерфейс IReplicaMetadata.
Пространство имен Terrasoft.Sync.
Класс Terrasoft.Sync.SyncRetryPolicy предоставляет API для выполнения повторной операции синхронизации. При обнаружении экземпляра TException синхронизация запускается повторно.
Пространство имен Terrasoft.Sync.
Интерфейс Terrasoft.Sync.IReplicaMetadata инкапсулирует метаданные синхронизации. Реализует работу с объектами ItemMetadata.
Методы
Возвращает объект метаданных синхронизации ItemMetadata по идентификатору во внешнем хранилище.
remoteItemId | Идентификатор внешнего хранилища. |
Обновляет метаданные после синхронизации.
oldItemMetaDatas | Метаданные предыдущей синхронизации. |
remoteItem | Элемент из внешнего хранилища. |
localItem | Элемент из хранилища Creatio. |
changesToBpm | Текущее направление синхронизации. |
context | Контекст синхронизации. |
Возвращает коллекцию объектов ItemMetadata, измененных после последней синхронизации в Creatio и не обработанных в процессе текущего сеанса синхронизации.
context | Контекст синхронизации. |
Обновляет метаданные для элементов синхронизации, измененных в Creatio. Если элемент был изменен в приложении после последней синхронизации SysMetadata, колонка Version будет заполнена датой модификации элемента. Для актуализации метаданных используется хранимая процедура ActualizeSysSyncMetaData.
userConnection | Пользовательское подключение. |
schemaName | Синхронизированное имя схемы. |
lastSyncVersion | Дата последней синхронизации. |
Создает новые записи в таблице SysSyncMetaData для деталей элемента синхронизации.
userConnection | Пользовательское подключение. |
detailEntityConfig | Экземпляр класса DetailEntityConfig. |
remoteItemName | Название элемента из внешнего хранилища. |
lastSyncVersion | Дата последней синхронизации. |
Возвращает идентификатор элемента во внешнем хранилище remoteId из метаданных по уникальному идентификатору элемента синхронизации в Creatio localId. Если элемент помечен как удаленный, то remoteId возращен не будет и метод возвратит false.
localId | Идентификатор сущности в хранилище Creatio. |
remoteId | Идентификатор элемента во внешнем хранилище. |
Возвращает идентификатор элемента во внешнем хранилище remoteId из метаданных по уникальному идентификатору элемента синхронизации в Creatio localId. Если элемент помечен как удаленный, то remoteId возращен не будет и метод возвратит false.
localId | Идентификатор сущности в хранилище Creatio. |
remoteItemName | Название элемента во внешнем хранилище. |
remoteId | Идентификатор элемента во внешнем хранилище. |
Возвращает дополнительные параметры extraParameters для элемента синхронизации из метаданных по localId. Если extraParameters не будут найдены, метод вернет false.
localId | Идентификатор сущности в хранилище Creatio. |
extraParameters | Параметры элемента во внешнем хранилище. |
Пространство имен Terrasoft.Sync.
Интерфейс Terrasoft.Sync.ISyncProvider обеспечивает взаимодействие с хранилищем данных. Изолирует агент синхронизации от деталей реализации хранилища данных.
Перечисление SyncConflictResolution
Пространство имен Terrasoft.Sync.
Перечисление Terrasoft.Sync.SyncConflictResolution содержит типы разрешения конфликта версий элемента сихронизации в хранилище Creatio и внешнем хранилище.
ApplyToLocal | Приоритет изменений внешнего хранилища. |
ApplyToRemote | Приоритет изменений хранилища Creatio. |
None | Не выполнять синхронизацию элемента. |
Перечисление SyncState
Пространство имен Terrasoft.Sync.
Перечисление Terrasoft.Sync.SyncState содержит состояния элемента синхронизации в текущем хранилище.
None | 0 | Не отслеживается. |
New | 1 | Новый элемент. |
Modified | 2 | Измененный элемент. |
Deleted | 3 | Удаленный элемент. |
Перечисление SyncAction
Пространство имен Terrasoft.Sync.
Перечисление Terrasoft.Sync.SyncAction содержит действия, которое необходимо выполнить над обьектом при применении изменений.
None | 0 | Не выполнять никаких действий. |
Create | 1 | Создать элемент. |
Update | 2 | Обновить элемент. |
Delete | 3 | Удалить элемент. |
CreateRecurringMaster | 4 | Создать повторяющийся элемент. |
Repeat | 5 | Повторить элемент. |
Перечисление SyncDirection
Пространство имен Terrasoft.Sync.
Перечисление Terrasoft.Sync.SyncDirection определяет направление синхронизации.
Способы определения направления синхронизации:
- На уровне агента. В этом случае направление применяется для всех синхронизируемых объектов.
- На уровне конкретного объекта. В этом случае направление перекрывает значение агента и устанавливает направление синхронизации для текущего объекта.
Download | 2 | Изменения применяются только в хранилище Creatio. |
Upload | 4 | Изменения применяются только во внешнем хранилище. |
DownloadAndUpload | Download | Upload | Двунаправленная синхронизация внешнего хранилища и хранилища Creatio. |