Конечные точки
Конечные точки используются для чтения или записи данных в определенном источнике.
Параметры ECOS-компонентов описаны по ecos-camel-core 1.17.1 на Apache Camel 4.14.8. Учитывайте различия поставок и версий библиотеки при подключении к своему приложению.
Подробнее - https://camel.apache.org/manual/endpoint.html
FileFromCamelDslEndpoint
Данный компонент позволяет работать с файлом, добавленным на форму конфигурации Camel DSL:
Ключ для использования компонента в camel-контексте: file-from-camel-dsl
FileFromCamelDslConsumer вычитывает данные из файла в виде ByteArray и кладет их в exchange для дальнейшей обработки
Пример:
- route:
from:
uri: "file-from-camel-dsl:randomName"
steps:
- process:
ref: csvToListOfDataProcessor
- split:
simple: "${body}"
steps:
- to: ecos-records-mutate:?sourceId=emodel/camel-example-employee
EcosRecordsSyncConsumer
Эндпоинт для последовательной выгрузки любого количества записей из указанного источника данных.
URI
ecos-records-sync-consumer:syncName
ecos-records-sync-consumer - константа
syncName - имя синхронизации. Может быть любым и используется для сохранения и доступа к состоянию. Т.е. если поменять syncName, то консьюмер будет работать «с нуля».
Выходные данные
Тип данных: List<DataValue>
Описание: Лист DataValue объектов с атрибутами, которые были загружены у записей. Глобальный идентификатор записи в атрибуты не попадает. Если он нужен, то следует его явно прописать в атрибутах:
attributes:
?id: ?id
Параметры
Параметр |
Тип |
Значение по умолчанию |
Обязательность |
Описание |
|---|---|---|---|---|
sourceId |
String? |
null |
Нет |
Идентификатор источника данных откуда мы будем загружать записи.
Можно не задавать если указан ecosType.
Примеры: emodel/source0, emodel/source1
|
ecosType |
String? |
null |
Нет |
Локальный идентификатор типа.
Если не указан sourceId, то он берется из типа.
Примеры: contract, attorney
|
predicate |
Predicate? |
Always True |
Нет |
Критерии поиска записей.
Примеры: {«t»: «eq», «a»: «_type», «v»: «emodel/type@case»}
|
initDate |
Instant |
1970-01-01T00:00:00Z |
Нет |
Нижняя граница даты создания записей для стратегий CREATED и MODIFIED; для KEY не используется.
При MODIFIED также применяется условие _created >= initDate: записи, созданные раньше, исключаются независимо от даты изменения.
Значение запоминается в состоянии синхронизации при первом запуске и в дальнейшем берется оттуда, поэтому изменение параметра у уже работающего консьюмера ни на что не влияет. Чтобы применить новую дату, нужно поменять syncName.
|
iterationStrategy |
CREATED_MODIFIED | CREATED | MODIFIED | KEY |
CREATED_MODIFIED |
Нет |
Какие стратегии перебора будут использованы (см. раздел «Стратегии» ниже).
CREATED_MODIFIED — сначала перебор по дате создания, затем по дате изменения;
CREATED — только перебор по дате создания;
MODIFIED — только перебор по дате изменения.
KEY — однократный обход по стабильному уникальному ключу keyAttribute.
|
keyAttribute |
String? |
null |
Для KEY |
Атрибут уникального ключа. Источник должен поддерживать сортировку и сравнение ключей |
keyType |
NUMBER | TEXT |
NUMBER |
Нет |
Тип ключа стратегии KEY |
partitions |
Int |
1 |
Нет |
Число разделов ключевого диапазона для KEY; 1 отключает разбиение |
partitionStrategy |
COUNT | SKIP |
null |
Нет |
Разбиение KEY по количеству записей в диапазонах либо по смещениям выборки. По умолчанию COUNT для NUMBER, SKIP для TEXT |
failedRecords |
RETRY | REGISTER |
RETRY |
Нет |
Повторять ошибочную пачку либо регистрировать проблемные записи и продолжать обход |
batchRetries |
Int |
3 |
Нет |
Число повторов пачки перед выделением ошибочных записей в режиме REGISTER |
maxFailedPerBatch |
Int |
-1 |
Нет |
Порог ошибок пачки. При отрицательном значении — 10% batchSize, минимум одна запись |
maxFailedTotal |
Int |
1000 |
Нет |
Порог общего количества зарегистрированных ошибок синхронизации |
stopOnMassFailure |
Boolean |
true |
Нет |
Останавливать синхронизацию при массовых ошибках |
batchSize |
Int |
100 |
Нет |
Размер пачки одновременно обрабатываемых записей |
attributes |
Map<String, String> |
Да |
Атрибуты для загрузки у записей |
|
addAuditAttributes |
Boolean |
true |
Нет |
Добавить атрибуты аудита (_created,_creator,_modified,_modifier) в список атрибутов для загрузки |
delay |
Long |
500 |
Нет |
Количество миллисекунд между обработкой пачек записей |
greedy |
Boolean |
false |
Нет |
Если true и количество обработанных записей больше нуля, то не ждать delay перед следующей обработкой, а сразу вызвать следующий poll |
initialDelay |
Long |
1000 |
Нет |
Задержка перед первой обработкой записей |
Примечание
Доп. параметры можно посмотреть в исходниках класса org.apache.camel.support.ScheduledPollEndpoint
Пример использования
- route:
from:
uri: ecos-records-sync-consumer:legalEntity-mgr-from
parameters:
delay: 30000
sourceId: emodel/source1
predicate:
t: eq
a: type
v: legalEntity
addAuditAttributes: true
attributes:
?id: ?id
id: ?localId
title: title
name: name
steps:
- to: log:ecos-records-sync
Принцип работы
Раз в {delay} миллисекунд идет запрос в источник данных {sourceId} который или задан явно или загружается из {ecosType}. Из источника данных загружается пачка записей размером <= {batchSize}. Загруженная пачка отправляется в обработку на указанные в роуте шаги.
В режиме failedRecords=RETRY состояние продвигается после успешной обработки пачки; при ошибке следующая попытка начинается с прежнего состояния. Режим REGISTER позволяет зарегистрировать проблемные записи и продолжить обработку с учётом заданных порогов ошибок.
Индивидуальная обработка записей
Если требуется индивидуальная обработка записей, то можно разделить элементы листа и обрабатывать каждый по отдельности:
- route:
from:
uri: ecos-records-sync-consumer:routeStage-mgr-from
parameters:
initialDelay: 10000
delay: 15000
sourceId: emodel/source1
predicate:
t: eq
a: type
v: routeStage
batchSize: 30
addAuditAttributes: true
attributes:
id: ?localId
title: title
name: name
steps:
- split:
simple: "${body}"
steps:
- to: log:result # в этих шагах каждый элемент будет обработан отдельно
Если требуется как-то индивидуально обработать записи и затем опять собрать их в одну пачку, то можно воспользоваться стратегией агрегации:
- beans:
- name: customJsonPatch
type: ru.citeck.ecos.camel.processor.data.JsonPatchOperationsProcessor
- name: collectToListStrategy
type: org.apache.camel.processor.aggregate.GroupedBodyAggregationStrategy
- route:
from:
uri: ecos-records-sync-consumer:routeStage-mgr-from
parameters:
initialDelay: 10000
delay: 15000
sourceId: emodel/source1
predicate:
t: eq
a: type
v: routeStage
batchSize: 30
addAuditAttributes: true
attributes:
id: ?localId
title: title
name: name
steps:
- split:
simple: "${body}"
aggregationStrategy: collectToListStrategy # это ключевое отличие
steps:
- setHeader:
name: JsonPatchOperations
constant:
- op: set
path: "_parentAtt"
value: templateRouteApprovingStages
- process:
ref: customJsonPatch
- to: log:result # после split мы будем обрабатывать лист, который собрался после индивидуальной обработки записей
Стратегии
Итерация выполняется одной или несколькими стратегиями. При каждом срабатывании poll’а (обработка следующей пачки записей) выполняется запрос следующей пачки записей через одну из описанных ниже стратегий. Используется первый не пустой результат и дальнейший перебор стратегий не выполняется. Каждая стратегия имеет состояние, которое хранит данные для продолжения итерации с последнего обработанного места.
Набор стратегий задается параметром iterationStrategy:
Значение |
Используемые стратегии |
|---|---|
CREATED_MODIFIED |
Обе стратегии: сначала «по дате создания», затем «по дате изменения». Значение по умолчанию |
CREATED |
Только «по дате создания». Изменения уже обработанных записей не подхватываются |
MODIFIED |
Только «по дате изменения» |
KEY |
Обход в порядке keyAttribute; последующие изменения записей по датам не отслеживаются |
Перебор по дате создания начинается с initDate. Начало перебора по дате изменения зависит от режима, как описано ниже; initDate дополнительно ограничивает дату создания. В стратегии KEY используются состояние ключа и, при включённом разбиении, состояния разделов. Для параллельного опроса задаётся scheduler.concurrentConsumers; у стандартного планировщика размер пула автоматически согласуется с числом потребителей, если scheduler.poolSize не задан явно.
По дате создания
Перебор идет по атрибуту _created от начального значения initDate.
Состояние:
Свойство |
Тип |
По умолчанию |
Описание |
|---|---|---|---|
totalCount |
Long |
-1 |
Ожидаемое полное количество всех записей для синхронизации.
Заполняется в начале и не обновляется в ходе итерации
|
lastCreated |
Instant |
Instant.EPOCH |
Дата последней созданной ноды, которую мы обработали |
lastRef |
EntityRef |
EntityRef.EMPTY |
Ссылка на последнюю обработанную запись |
skipCount |
Int |
0 |
Количество элементов, которые нужно пропустить при следующем запросе.
Используется для обработки записей, у которых дата создания совпадает.
|
processedCount |
Long |
0 |
Количество обработанных записей |
lastCreatedCounter |
Int |
0 |
Счетчик записей с одинаковой датой создания.
Используется чтобы в результирующих данных скорректировать дату создания добавив к ней lastCreatedCounter микросекунд.
Это нужно чтобы после загрузки этих данных в другую БД сохранился порядок при сортировке по полю _created.
|
Особенности стратегии:
Сохранение порядка — если в выгружаемых данных записи имеют одинаковую дату создания, то первая из них будет иметь оригинальную дату, а все последующие будут иметь дату создания на N микросекунд больше. Количество микросекунд увеличивается с каждой новой записью с одинаковой датой создания.
По дате изменения
Перебор идет по атрибуту _modified. В режиме CREATED_MODIFIED начальное значение — дата начала синхронизации, в режиме MODIFIED — Instant.EPOCH. При ненулевой initDate в обоих режимах дополнительно применяется условие _created >= initDate.
Состояние:
Свойство |
Тип |
По умолчанию |
Описание |
|---|---|---|---|
lastModified |
Instant |
Дата начала синхронизации для CREATED_MODIFIED; Instant.EPOCH для MODIFIED |
Дата последней измененной записи, которую мы обработали |
lastRef |
EntityRef |
EntityRef.EMPTY |
Ссылка на последнюю обработанную запись |
idsWithLastModified |
List<String> |
[] |
Локальные идентификаторы уже обработанных записей с датой lastModified. Исключаются из следующей выборки, чтобы записи с одинаковой датой не обрабатывались повторно |
processedCount |
Long |
0 |
Количество обработанных записей |
Особенности стратегии:
Синхронизация проходит только для тех записей, которые были созданы до даты создания последней синхронизованной записи из первой стратегии.
EcosRecordsMutateEndpoint
Эндпоинт для выполнения мутации через RecordsAPI
URI
ecos-records-mutate:?sourceId={sourceId}
ecos-records-mutate - константа
sourceId - идентификатор источника данных куда следует отправить запрос мутации. Например: „emodel/contract“, „emodel/custom-type“
Параметры
Параметр |
Тип |
Значение по умолчанию |
Обязательность |
Описание |
|---|---|---|---|---|
sourceId |
String? |
null |
Нет |
Идентификатор источника данных, куда отправляется запрос мутации.
Можно не задавать, если указан ecosType.
|
ecosType |
String? |
null |
Нет |
Локальный идентификатор типа. Если sourceId не указан, источник данных берется из типа.
Если не заданы ни sourceId, ни ecosType, маршрут не запустится с ошибкой «You should define sourceId or ecosType».
|
ignoreIdScalarAtt |
Boolean |
false |
Нет |
Если true, атрибут ?id удаляется из данных и не используется как ссылка на изменяемую запись.
Атрибут id сохраняется и может использоваться источником для обновления существующей записи.
Если false, значение ?id определяет, какая запись будет изменена.
|
logRecords |
FULL | IDS | ERRORS |
FULL |
Нет |
FULL — атрибуты запросов и результат; IDS — идентификаторы вместо полных атрибутов; ERRORS — только неуспешные мутации |
Примечание
Мутация выполняется от имени системы (AuthContext.runAsSystem), то есть без учета прав текущего пользователя.
Входные данные
Конечная точка принимает либо одно map-like значение, либо список.
Поддерживаются объекты DataValue, ObjectData, строка с JSON-объектом, коллекция таких значений и массив DataValue. Обычную Java Map предварительно преобразуйте в DataValue или ObjectData.
map-like значение по структуре содержит список атрибутов, которые будут использованы для мутации.
Если среди атрибутов есть «?id» с полным ref мутируемой сущности, то мутация будет выполнена именно для этой сущности.
Если среди атрибутов есть «id» (локальный id сущности), то мутация либо обновит существующую сущность, либо создаст новую если такой еще нет.
Выход: тело сохраняется; заголовок recordsMutated содержит список строковых ссылок на сохранённые записи. Для пустого набора мутаций заголовок не устанавливается заново.
- route:
from:
uri: direct:save-imported-record
steps:
- setBody:
constant: '{"id":"example","_name":"Пример"}'
- to:
uri: 'ecos-records-mutate:'
parameters:
sourceId: emodel/import-test
logRecords: IDS
- log: '${header.recordsMutated}'
EcosEventEndpoint
Эндпоинт для работы с событиями ECOS. Может использоваться и как потребитель (подписка на событие), и как производитель (публикация события).
Примеры подписки на события с фильтрами приведены в разделе Подписка на событие Citeck.
URI
ecos-event:eventType
ecos-event - константа
eventType - тип события. Обязателен. Например: record-created, record-status-changed
Параметры
Параметр |
Тип |
Значение по умолчанию |
Обязательность |
Описание |
|---|---|---|---|---|
attributes |
Map<String, String> |
Нет |
Атрибуты события, которые нужно получить. Ключ — имя атрибута в теле сообщения, значение — схема атрибута.
Телом сообщения становится объект со всеми перечисленными атрибутами.
|
|
attribute |
String? |
null |
Нет |
Один атрибут вместо набора. Телом сообщения становится значение самого атрибута, без объекта-обертки.
Задавать одновременно с attributes нельзя — маршрут не запустится с ошибкой «You should define property „attribute“ or „attributes“ but not both».
|
filter |
Predicate |
Always True |
Нет |
Условие, при котором событие попадет в маршрут |
transactional |
Boolean |
false |
Нет |
Если true, обработка выполняется в транзакции источника события, и исключение в маршруте пробрасывается наружу — то есть приводит к откату транзакции.
Если false, ошибка обработки на источник события не влияет.
|
outputType |
DEFAULT | DATA_VALUE | JSON_STRING | JAVA |
DEFAULT |
Нет |
Во что преобразуется тело сообщения:
DEFAULT и DATA_VALUE — объект DataValue (поведение совпадает);
JSON_STRING — строка с JSON;
JAVA — обычный объект Java (Map, List, String и т.д.).
|
Параметры attributes, attribute, filter, transactional и outputType относятся к потребителю событий. Производитель публикует событие указанного типа из тела сообщения.
Пример подписки
- route:
from:
uri: 'ecos-event:record-created'
parameters:
attribute: 'record?id'
outputType: JSON_STRING
steps:
- to: log:record-was-created
Публикация события
При использовании эндпоинта в шаге to тело сообщения публикуется как событие указанного типа. Источник события — camel. Публикация выполняется от имени системы (AuthContext.runAsSystem).
- route:
from:
uri: .....
steps:
- to: 'ecos-event:my-custom-event'
EcosRecordsQueryEndpoint
Эндпоинт для выполнения запроса к RecordsAPI.
URI
ecos-records-query:
Параметры
Параметр |
Тип |
Значение по умолчанию |
Обязательность |
Описание |
|---|---|---|---|---|
outputType |
DEFAULT | DATA_VALUE | JSON_STRING | JAVA |
DEFAULT |
Нет |
В каком виде атрибуты каждой найденной записи попадут в результат:
DEFAULT и DATA_VALUE — объект DataValue;
JSON_STRING — строка с JSON;
JAVA — обычный объект Java.
|
Входные данные
Тело сообщения — объект, преобразуемый в RecordsQuery. Дополнительно в нем можно указать поле attributes: массив имен атрибутов либо объект вида «псевдоним — атрибут».
Выходные данные
Тело сообщения заменяется списком. Если attributes не заданы, элементы списка — строковые ссылки на найденные записи. Если заданы — атрибуты каждой записи (идентификатор добавляется автоматически, если его нет среди запрошенных атрибутов) в формате, заданном outputType.
Заголовки:
Заголовок |
Значение |
|---|---|
EcosRecordsQueryHasMore |
Признак того, что есть еще записи за пределами выданной страницы |
EcosRecordsQueryTotalCount |
Общее количество найденных записей |
Примечание
Запрос выполняется от имени системы, то есть без учета прав текущего пользователя.
- route:
from:
uri: direct:query-imported-records
steps:
- setBody:
constant: >-
{"sourceId":"emodel/import-test","language":"predicate",
"query":{"t":"eq","a":"id","v":"example"},
"page":{"maxItems":100},"attributes":{"name":"_name"}}
- to:
uri: 'ecos-records-query:'
parameters:
outputType: DATA_VALUE
- log: 'Всего: ${header.EcosRecordsQueryTotalCount}'
EcosRecordsDeleteEndpoint
Эндпоинт для удаления записей через RecordsAPI.
URI
ecos-records-delete:
Параметры
Параметр |
Тип |
Значение по умолчанию |
Обязательность |
Описание |
|---|---|---|---|---|
sourceId |
String? |
null |
Нет |
Идентификатор источника данных, который подставляется ссылкам, заданным без него.
Значение можно переопределить для конкретного сообщения заголовком EcosRecordsDeleteSourceId.
|
ignoreInvalidRefs |
Boolean |
false |
Нет |
Если true, локальная проверка ссылок отключается, но ссылки остаются в запросе к Records API. Их успешное игнорирование не гарантируется. Если false, ссылка, не прошедшая проверку, вызывает ошибку |
Входные данные
Тело сообщения — одна ссылка либо коллекция ссылок. Допустимые формы: String, EntityRef, Map, DataValue, ObjectData; в объектах идентификатор читается сначала из атрибута ?id, а при его отсутствии — из id.
Тело сообщения после обработки не изменяется. Перед вызовом удаления список ссылок записывается в лог синхронизации под именем records-delete. Наличие этой записи в логе не подтверждает успешное удаление.
Примечание
Удаление выполняется от имени системы, то есть без учета прав текущего пользователя.
- route:
from:
uri: direct:delete-example-record
steps:
- setBody:
constant: emodel/import-test@example
- to:
uri: 'ecos-records-delete:'
parameters:
ignoreInvalidRefs: false
EcosAttributesMapperEndpoint
Эндпоинт для приведения «сырых» строковых значений атрибутов к модели атрибутов ECOS-типа. Применяется при импорте данных из внешних источников, где все значения приходят строками.
URI
ecos-attributes-mapper:typeId
ecos-attributes-mapper - константа
typeId - локальный идентификатор ECOS-типа, по модели атрибутов которого выполняется преобразование. Обязателен
Параметры
Параметр |
Тип |
Значение по умолчанию |
Обязательность |
Описание |
|---|---|---|---|---|
delimiter |
String |
, |
Нет |
Разделитель, по которому строка разбивается на несколько значений для многозначных атрибутов |
assocMapping |
JSON |
{} |
Нет |
Карта вида «атрибут — список атрибутов», по которым искать связанную запись.
Задается строкой с JSON. По умолчанию поиск идет по атрибуту _name.
|
Входные и выходные данные
Тело сообщения — список объектов DataValue, каждый из которых представляет собой набор пар «идентификатор атрибута — строковое значение». Тело заменяется тем же списком с преобразованными значениями:
Тип атрибута |
Преобразование |
|---|---|
BOOLEAN |
Распознаются значения да, нет, yes, no, true, false |
DATE |
Значение OffsetDateTime преобразуется в календарную дату с сохранением даты в исходном смещении часового пояса. Если значение не разбирается, строка остается без изменения |
OPTIONS |
Отображаемое название варианта заменяется его значением |
ASSOC, PERSON, AUTHORITY_GROUP, AUTHORITY |
Значение ищется среди записей по атрибутам из assocMapping и заменяется ссылкой на найденную запись.
Если запись не найдена, значение используется как готовая ссылка только при заполненных appName, sourceId и localId. Иначе результат — null.
|
- route:
from:
# На входе список DataValue со строковыми значениями атрибутов типа import-test.
uri: direct:map-imported-attributes
steps:
- to:
uri: ecos-attributes-mapper:import-test
parameters:
delimiter: ';'
assocMapping: '{"department":["code","_name"]}'
Замените import-test и department на тип и атрибут своей модели. Компонент не сохраняет записи; после преобразования используйте ecos-records-mutate.
EcosFtpEndpoint
Эндпоинт для работы с FTP, SFTP и FTPS, в котором адрес и учетные данные берутся из конечной точки ECOS и связанного с ней секрета. Благодаря этому в тексте маршрута не оказывается ни пароля, ни ключа.
URI
ecos-ftp:endpointId
ecos-ftp - константа
endpointId - идентификатор конечной точки ECOS, из которой берутся протокол, адрес, каталог и учетные данные. Обязателен
Параметры
Собственных параметров у эндпоинта нет. Все остальные параметры строки запроса передаются без изменений в стандартный компонент camel-ftp, camel-sftp или camel-ftps, которому эндпоинт делегирует работу.
Предупреждение
Параметры, содержащие учетные данные, запрещены и приводят к ошибке: username, password, account, privatekey и производные от него, passphrase, keypair, а также параметры, последний сегмент имени которых заканчивается на username, password, keypassword или passphrase, например proxyUsername или ftpClient.keyStore.password. Проверка не зависит от регистра. Пароли и ключи задаются через секрет конечной точки ECOS.
Для секрета BASIC имя пользователя и пароль берутся из секрета; имя пользователя также может быть указано в URL конечной точки. Для PRIVATE_KEY имя пользователя обязательно задается в URL, например sftp://deploy@host/outbox, а ключ берется из секрета. Пароль в URL запрещен.
Входные и выходные данные
Совпадают с входными и выходными данными стандартного компонента camel-ftp: в режиме производителя тело сообщения — содержимое файла, имя задается заголовком CamelFileName; в режиме потребителя маршрут получает прочитанные файлы. Собственных заголовков эндпоинт не добавляет.
Примечание
Если для SFTP отключена проверка ключа хоста (strictHostKeyChecking=no, значение по умолчанию в camel-ftp), в лог выводится предупреждение.
- route:
from:
uri: direct:upload-csv
steps:
- setHeader:
name: CamelFileName
constant: export.csv
- to: 'ecos-ftp:export-sftp?binary=true'
На вход direct:upload-csv передаётся содержимое файла. Конечная точка ECOS export-sftp должна быть настроена заранее. Полный пример выгрузки CSV см. в каталоге примеров.
EcosExcelStreamReadEndpoint
Эндпоинт для потокового построчного чтения XLSX-файла. В отличие от ExcelToListOfDataProcessor, файл не загружается в память целиком, а выдается в маршрут пачками строк, поэтому подходит для больших файлов.
URI
ecos-excel-stream-read:contentRef
ecos-excel-stream-read - константа
contentRef - ссылка на запись с содержимым XLSX-файла. Обязательна. Тип содержимого должен быть XLSX
Параметры
Параметр |
Тип |
Значение по умолчанию |
Обязательность |
Описание |
|---|---|---|---|---|
batchSize |
Int |
100 |
Нет |
Количество строк, накапливаемых перед отправкой пачки в маршрут |
sheetName |
String? |
null |
Нет |
Название листа Excel |
headRowNumber |
Int? |
null |
Нет |
Номер строки с заголовками, если он отличается от значения по умолчанию |
customAttNames |
Map<String, String> |
{} |
Нет |
Переименование колонок: ключ — название колонки в заголовке файла, значение — желаемое имя атрибута |
Выходные данные
Тело сообщения — List<DataValue>, по одному объекту на строку файла в формате «заголовок колонки — значение ячейки». Значения даты и времени сдвигаются на часовой пояс пользователя, десятичные числа передаются строкой без экспоненциальной записи.
По ходу чтения публикуются события управления импортом: начало, обработка пачки, завершение и ошибка.
Входное тело не используется: файл определяется ссылкой в URI.
- route:
from:
uri: ecos-excel-stream-read:emodel/import-file@example
parameters:
batchSize: 100
sheetName: Sheet1
headRowNumber: 1
steps:
- split:
simple: '${body}'
steps:
- to: 'ecos-records-mutate:?sourceId=emodel/import-test'
EcosRecordsValidateEndpoint
URI: ecos-records-validate:. Производитель сравнивает ожидаемые атрибуты с целевыми записями и регистрирует расхождения без изменения целевых записей. Контекст должен предоставлять реестр расхождений синхронизации.
Параметры
Параметр |
Тип |
По умолчанию |
Назначение |
|---|---|---|---|
sourceId |
String? |
null |
Целевой источник; обязателен sourceId либо ecosType |
ecosType |
String? |
null |
Тип, из которого определяется источник при отсутствии sourceId |
syncName |
String? |
null |
Имя синхронизации в реестре расхождений. Если не задано, берётся заголовок журнала синхронизации от ecos-records-sync-consumer |
compare |
String |
Пустая строка |
Режимы сравнения через запятую: |
skipAttributes |
String |
Пустая строка |
Пропускаемые атрибуты через запятую; завершающий |
dateTolerance |
String |
PT0S |
Неотрицательный интервал ISO-8601 для сравнения DATETIME, например PT5S |
maxOpenDiffs |
Int |
1000 |
Максимум записей с открытыми расхождениями; отрицательное значение снимает ограничение |
Вход: тот же формат набора атрибутов, что у ecos-records-mutate. Запись определяется по ?id либо по локальному id и sourceId. Остальные атрибуты — ожидаемые значения.
Выход: тело не меняется. Расхождения регистрируются, а ранее найденные расхождения для совпавших записей закрываются. Чтение и регистрация выполняются от имени системы. Отсутствующая целевая запись регистрируется как расхождение _notExists.
- route:
from:
uri: direct:validate-import
steps:
- setBody:
constant: '{"id":"example","_name":"Пример","amount":1500}'
- to:
uri: 'ecos-records-validate:'
parameters:
sourceId: emodel/import-test
syncName: import-check
compare: amount=NUMBER
skipAttributes: '_modified,_modifier'
Компоненты импорта из Jira и GitLab
Потребители наследуют параметры ScheduledPollEndpoint, например delay и initialDelay. В примерах {{gitlab.url}} и {{gitlab.token}} — свойства Camel, задаваемые в окружении.
Компоненты GitLab
Оба компонента являются потребителями, периодически опрашивают GitLab и сохраняют состояние синхронизации, поэтому при следующем запуске продолжают с того места, где остановились. Одновременный запуск нескольких опросов (например, на разных узлах) не происходит: повторный запуск пропускается.
gitlab-commits-sync
Входные данные: Входное тело отсутствует: потребитель.
Выгружает коммиты проектов, обновленных с момента последней синхронизации.
URI: gitlab-commits-sync:syncName, где syncName — имя синхронизации, под которым хранится состояние. Обязательно.
Параметр |
Тип |
Значение по умолчанию |
Обязательность |
Описание |
|---|---|---|---|---|
gitLabEndpoint |
String |
Да |
Адрес GitLab |
|
gitLabToken |
String |
Да |
Токен доступа к GitLab |
|
batchSize |
Int |
100 |
Нет |
Количество коммитов, накапливаемых перед отправкой пачки в маршрут |
skipErrorRegex |
String? |
null |
Нет |
Регулярное выражение. Ошибки GitLab, текст которых ему соответствует, пропускаются вместо прерывания опроса |
Выходные данные: List<DataValue> — исходный JSON коммитов.
Пример YAML:
- route:
from:
uri: gitlab-commits-sync:example-sync
parameters:
gitLabEndpoint: '{{gitlab.url}}'
gitLabToken: '{{gitlab.token}}'
delay: 60000
steps:
- to: log:gitlab-import
gitlab-merge-requests-sync
Входные данные: Входное тело отсутствует: потребитель.
Выгружает запросы на слияние, созданные с момента последней синхронизации, в порядке возрастания даты создания.
URI: gitlab-merge-requests-sync:syncName.
Параметры gitLabEndpoint, gitLabToken и skipErrorRegex совпадают с параметрами gitlab-commits-sync. Параметра batchSize у этого компонента нет: за один опрос выдается одна пачка.
Выходные данные: List<DataValue> — исходный JSON запросов на слияние.
Пример YAML:
- route:
from:
uri: gitlab-merge-requests-sync:example-sync
parameters:
gitLabEndpoint: '{{gitlab.url}}'
gitLabToken: '{{gitlab.token}}'
delay: 60000
steps:
- to: log:gitlab-import
Компоненты Jira
Для производителей Jira требуется общий контекст: свойства обмена _workspace и link-project:project. Их заполняет jira-issues; при вызове через direct: передаёт вызывающий маршрут. Заголовки целевых записей указаны у каждого компонента.
Параметр jiraClient — ссылка на бин ru.citeck.ecos.camel.jira.api.JiraApiClient. Его endpointId задаёт конечную точку ECOS с адресом Jira и секретом BASIC или TOKEN:
- beans:
- name: jiraClient
type: ru.citeck.ecos.camel.jira.api.JiraApiClient
properties:
endpointId: jira-host
Примеры производителей предполагают этот бин и переданный контекст. Входное тело — исходная задача после split. Сохраняйте её в переменной и восстанавливайте перед следующим компонентом, если предыдущий заменил тело.
Схема работы такая: потребитель jira-issues выдает в маршрут исходный JSON задачи Jira и дополнительно кладет в свойства обмена рабочее пространство и ссылку на проект. Дальше производители transform-jira-* превращают части этой задачи в наборы атрибутов, готовые к сохранению через ecos-records-mutate, а производители import-jira-* сами создают связанные записи и проставляют ссылки на них в задаче EPT.
Примечание
Производители import-jira-*, transform-jira-comment и transform-jira-worklog ожидают в заголовке сообщения ссылку на целевую запись: eptIssueRef для большинства из них, commentLinkToRecord для комментариев и worklogLinkToRecord для записей о затраченном времени. Свойства обмена с рабочим пространством и проектом заполняет jira-issues.
jira-issues
Входные данные: Входное тело отсутствует. Проекты с импортируемыми ключами должны существовать в Citeck и иметь связанное рабочее пространство.
Потребитель. Периодически перебирает задачи одного или нескольких проектов Jira, запоминая смещение по каждому проекту; после обхода последнего проекта цикл начинается заново.
URI: jira-issues:name, где name — имя синхронизации. Обязательно.
Параметр |
Тип |
Значение по умолчанию |
Обязательность |
Описание |
|---|---|---|---|---|
projectKey |
String |
Да |
Ключи проектов Jira через запятую. Не используется, если задан issueKey |
|
jiraClient |
JiraApiClient |
Да |
Ссылка на бин клиента Jira REST API |
|
issueKey |
String |
«» |
Нет |
Если задан, импортируется ровно одна указанная задача, после чего потребитель останавливается.
Значение должно содержать префикс проекта, например PROJECT-1
|
Выходные данные: список с исходным JSON задач — по 10 задач за один опрос в обычном режиме и одна задача в режиме issueKey.
Свойства обмена: рабочее пространство задачи и ссылка на проект (link-project:project) — они нужны остальным компонентам Jira.
Пример YAML:
- beans:
- name: jiraClient
type: ru.citeck.ecos.camel.jira.api.JiraApiClient
properties:
endpointId: jira-host
- route:
from:
uri: jira-issues:example-import
parameters:
jiraClient: '#bean:jiraClient'
projectKey: DEMO
delay: 5000
steps:
- split:
simple: '${body}'
steps:
- to: direct:process-jira-issue
transform-jira-issue
URI: transform-jira-issue:.
Входные данные: Один DataValue с JSON задачи и свойства обмена _workspace и link-project:project. Заголовок eptIssueRef не требуется.
Производитель. Преобразует исходную задачу Jira в набор атрибутов задачи EPT. Правила преобразования задаются не параметрами, а свойствами обмена, имена которых можно переопределить:
Все параметры *Property имеют тип String и необязательны; значения по умолчанию приведены в таблице.
Параметр |
Значение по умолчанию |
Какое свойство обмена задает |
|---|---|---|
attributesMappingProperty |
attributesMapping |
Карта «путь в JSON задачи Jira — атрибут задачи EPT» |
valuesMappingProperty |
valuesMapping |
Карта «атрибут — карта соответствия значений Jira значениям EPT» |
valuesConverterProperty |
valuesConverter |
Карта «атрибут — имя конвертера значения» |
staticAttributesProperty |
staticAttributes |
Карта атрибутов с постоянными значениями, добавляемых к каждой задаче |
linksMappingProperty |
linksMapping |
Карта «тип связи в Jira — атрибут связи в EPT» |
Обязательный параметр jiraClient используется для получения списка наблюдателей задачи.
Параметр |
Тип |
Обязательность |
Описание |
|---|---|---|---|
jiraClient |
JiraApiClient |
Да |
Ссылка на бин клиента Jira, например |
Выходные данные: один объект DataValue с атрибутами задачи EPT: сопоставленные поля, наблюдатели, связи с другими задачами, постоянные атрибуты, идентификатор, номер задачи, а для подзадач — ссылка на родительскую задачу.
Пример YAML:
- route:
from:
uri: direct:transform-jira-issue
steps:
- setProperty:
name: attributesMapping
constant: '{"fields.summary":"summary"}'
- to:
uri: 'transform-jira-issue:'
parameters:
jiraClient: '#bean:jiraClient'
transform-jira-comment
URI: transform-jira-comment:.
Параметры: собственных параметров нет.
Входные данные: Один DataValue с JSON задачи и общий контекст импорта. Обязательный заголовок commentLinkToRecord — ссылка на целевую запись.
Производитель без параметров. Преобразует комментарии задачи в список объектов, готовых к сохранению как комментарии Citeck. Заголовок commentLinkToRecord задает запись, к которой они относятся.
При преобразовании текст комментария очищается от особенностей Jira: ссылки на вложения и миниатюры заменяются на адреса содержимого в Citeck, упоминания пользователей — на упоминания в формате Citeck, у изображений убирается заданный в Jira размер.
Пример YAML:
- route:
from:
uri: direct:transform-jira-comment
steps:
- setHeader:
name: commentLinkToRecord
constant: emodel/ept-issue@DEMO-1
- to:
uri: 'transform-jira-comment:'
transform-jira-worklog
URI: transform-jira-worklog:.
Параметры: собственных параметров нет.
Входные данные: Один DataValue с JSON задачи и общий контекст импорта. Обязательный заголовок worklogLinkToRecord — ссылка на целевую запись.
Производитель без параметров. Преобразует записи о затраченном времени в список объектов учета времени Citeck. Заголовок worklogLinkToRecord задает запись, к которой они привязываются. Длительность пересчитывается из секунд в миллисекунды.
Пример YAML:
- route:
from:
uri: direct:transform-jira-worklog
steps:
- setHeader:
name: worklogLinkToRecord
constant: emodel/ept-issue@DEMO-1
- to:
uri: 'transform-jira-worklog:'
import-jira-releases
URI: import-jira-releases:.
Входные данные: Один DataValue с fields.fixVersions и fields.versions и общий контекст импорта. Обязательный заголовок eptIssueRef — ссылка на целевую запись.
Производитель. Создает или обновляет записи релизов из версий задачи Jira и проставляет их в атрибуты задачи EPT «Исправить в версии» и «Затронутые версии». Обязательный параметр jiraClient используется для получения полной информации о версии.
Статус релиза берется из признака выпуска в Jira. Выходные данные — список ссылок на созданные релизы.
Параметр |
Тип |
Обязательность |
Описание |
|---|---|---|---|
jiraClient |
JiraApiClient |
Да |
Ссылка на бин клиента Jira, например |
Пример YAML:
- route:
from:
uri: direct:import-jira-releases
steps:
- setHeader:
name: eptIssueRef
constant: emodel/ept-issue@DEMO-1
- to:
uri: 'import-jira-releases:'
parameters:
jiraClient: '#bean:jiraClient'
import-jira-attachment
URI: import-jira-attachment:.
Входные данные: Один DataValue с JSON задачи, содержащий fields.attachment. Обязательный заголовок eptIssueRef — ссылка на целевую запись.
Производитель. Скачивает вложения задачи Jira и сохраняет их как документы Citeck, вложенные в задачу EPT. Обязательный параметр jiraClient используется для загрузки содержимого.
Автор и даты создания и изменения переносятся из Jira. Выходные данные — список ссылок на созданные документы.
Параметр |
Тип |
Обязательность |
Описание |
|---|---|---|---|
jiraClient |
JiraApiClient |
Да |
Ссылка на бин клиента Jira, например |
Пример YAML:
- route:
from:
uri: direct:import-jira-attachment
steps:
- setHeader:
name: eptIssueRef
constant: emodel/ept-issue@DEMO-1
- to:
uri: 'import-jira-attachment:'
parameters:
jiraClient: '#bean:jiraClient'
import-jira-dev-info
URI: import-jira-dev-info:.
Входные данные: Один DataValue с JSON задачи и свойство обмена _workspace. Обязательный заголовок eptIssueRef — ссылка на целевую запись.
Производитель. Переносит связанные с задачей коммиты и запросы на слияние: из внешних ссылок Jira создаются записи коммитов и запросов на слияние, привязанные к задаче. Обязательный параметр jiraClient используется для получения внешних ссылок.
Тело сообщения этот компонент не изменяет.
Параметр |
Тип |
Обязательность |
Описание |
|---|---|---|---|
jiraClient |
JiraApiClient |
Да |
Ссылка на бин клиента Jira, например |
Пример YAML:
- route:
from:
uri: direct:import-jira-dev-info
steps:
- setHeader:
name: eptIssueRef
constant: emodel/ept-issue@DEMO-1
- to:
uri: 'import-jira-dev-info:'
parameters:
jiraClient: '#bean:jiraClient'
import-jira-component
URI: import-jira-component:.
Параметры: собственных параметров нет.
Входные данные: Один DataValue с fields.components и общий контекст импорта. Обязательный заголовок eptIssueRef — ссылка на целевую запись.
Производитель без параметров. Создает или обновляет записи компонентов из компонентов задачи Jira и проставляет их в атрибут «Компоненты» задачи EPT. Выходные данные — список ссылок на созданные компоненты.
Пример YAML:
- route:
from:
uri: direct:import-jira-component
steps:
- setHeader:
name: eptIssueRef
constant: emodel/ept-issue@DEMO-1
- to:
uri: 'import-jira-component:'
import-jira-sprint
URI: import-jira-sprint:.
Входные данные: Один DataValue с JSON задачи и общий контекст импорта. Обязательный заголовок eptIssueRef — ссылка на целевую запись.
Производитель. Создает или обновляет записи спринтов из спринта задачи Jira и проставляет их в атрибут «Спринт» задачи EPT.
Параметр |
Тип |
Значение по умолчанию |
Обязательность |
Описание |
|---|---|---|---|---|
sprintFieldId |
String |
Да |
Имя пользовательского поля Jira, в котором хранятся данные спринта.
Поддерживаются оба формата: объект JSON и устаревший строковый формат Greenhopper
|
Статус спринта определяется по его состоянию в Jira: активный — «в работе», закрытый — «закрыт», остальные — «новый».
Выходные данные: список строковых ссылок на созданные или обновленные спринты.
Пример YAML:
- route:
from:
uri: direct:import-jira-sprint
steps:
- setHeader:
name: eptIssueRef
constant: emodel/ept-issue@DEMO-1
- to:
uri: 'import-jira-sprint:'
parameters:
sprintFieldId: customfield_10020