1C OData Connector

Коннектор onec-odata предназначен для интеграции UniBPM с системами 1С через OData API.

Коннектор позволяет BPMN‑процессам:

• получать объекты из 1С
• выполнять выборки
• создавать документы
• обновлять объекты
• удалять объекты

Интеграция реализована через External Task механизм UniBPM.

Архитектура

BPMN Process
     │
     ▼
External Task (UniBPM Engine)
     │
Kafka
     │
     ▼
Integration Runtime
     │
     ▼
1C OData API

1. BPMN вызывает External Task\
2. UniBPM публикует задание в Kafka\
3. Integration Runtime выполняет HTTP запрос к 1С\
4. Результат возвращается в процесс

Конфигурация

Коннектор активируется через application.yaml.

unibpm:
  integration:
    connectors:
      onec-odata:
        enabled: true
        servers:
          - name: main
            baseUrl: http://1c-server/odata/standard.odata
            authType: BASIC
            username: odata_user
            password: secret
            timeoutMs: 15000

Параметры

Параметр Описание

name логическое имя сервера baseUrl базовый URL OData authType тип аутентификации (BASIC, NONE) username пользователь password пароль timeoutMs HTTP таймаут

Использование в BPMN

External Task должен содержать следующие Extension Properties.

Property Значение

uni.connector onec-odata uni.action execute uni.version v1

Параметры OData

Основные

Property Описание

odata.server имя сервера odata.entitySet сущность 1С odata.operation операция result.var переменная процесса

Операции

GET_BY_KEY

Получение объекта по GUID.

Пример

odata.server = main
odata.entitySet = Catalog_Сотрудники
odata.operation = GET_BY_KEY
odata.key = 7a0d9498-b69f-11ee-8408-d00d1e38dc0c
result.var = employee

HTTP запрос:

GET /Catalog_Сотрудники(guid'7a0d9498-b69f-11ee-8408-d00d1e38dc0c')

QUERY

Выборка объектов.

Параметры

Property OData

odata.filter $filter odata.select $select odata.expand $expand odata.top $top odata.skip $skip odata.orderBy $orderby

Пример

odata.server = main
odata.entitySet = Catalog_Сотрудники
odata.operation = QUERY
odata.filter = Code eq '0000-00028'
odata.top = 1
result.var = employee

CREATE

Создание объекта.

Пример

Создание документа Отпуск.

odata.server = main
odata.entitySet = Document_Отпуск
odata.operation = CREATE
result.var = createdVacation

Payload передается в переменной процесса.

{
  "Date": "2026-03-05T12:00:00",
  "Организация_Key": "3ea34f66-a952-11e4-80ca-884e52ab44da",
  "Сотрудник_Key": "7a0d9498-b69f-11ee-8408-d00d1e38dc0c",
  "ДатаНачалаОсновногоОтпуска": "2026-03-21T00:00:00",
  "ДатаОкончанияОсновногоОтпуска": "2026-03-31T00:00:00",
  "КоличествоДнейОсновногоОтпуска": 11
}

UPDATE

Обновление объекта.

odata.server = main
odata.entitySet = Document_Отпуск
odata.operation = UPDATE
odata.key = ab86e430-17ef-11f1-9379-d00d1e38dc0c

HTTP:

PATCH /Document_Отпуск(guid'ab86e430-17ef-11f1-9379-d00d1e38dc0c')

DELETE

Удаление объекта.

odata.server = main
odata.entitySet = Document_Отпуск
odata.operation = DELETE
odata.key = ab86e430-17ef-11f1-9379-d00d1e38dc0c

HTTP:

DELETE /Document_Отпуск(guid'ab86e430-17ef-11f1-9379-d00d1e38dc0c')

Ошибки

Коннектор поддерживает две политики обработки ошибок.

Policy Поведение

FAIL_TASK External Task завершится с ошибкой BPMN_ERROR генерируется BPMN Error

Специализированные обработчики (ZUP)

Помимо универсального обработчика onec-odata.execute, платформа поддерживает предметные обработчики, инкапсулирующие бизнес‑логику конкретных операций 1С.

Они упрощают BPMN‑процессы и автоматически формируют payload.

В текущей версии доступен обработчик:

Создание документа Отпуск

Handler:

uni.connector = onec-zup
uni.action = vacation.create
uni.version = v1

Обработчик автоматически формирует документ Document_Отпуск в 1С.

Обязательные параметры

vacation.server
vacation.organizationKey
vacation.employeeKey
vacation.startDate
vacation.endDate
vacation.registrationPeriod

Необязательные параметры

vacation.documentDate
vacation.absenceStartDate
vacation.absenceEndDate
vacation.reason
vacation.deletionMark
vacation.paymentLeadDays
vacation.select

Полный список Extension Properties

Пример

uni.connector = onec-zup
uni.action = vacation.create
uni.version = v1

vacation.server = main
vacation.organizationKey = 3ea34f66-a952-11e4-80ca-884e52ab44da
vacation.employeeKey = 4373514a-a818-11e7-8115-000c29d419fb

vacation.startDate = 2026-03-21
vacation.endDate = 2026-03-31
vacation.registrationPeriod = 2026-03-01

result.var = createdVacation
error.policy = FAIL_TASK

Что делает handler

Обработчик автоматически:

• рассчитывает КоличествоДнейОсновногоОтпуска
• устанавливает ДатаНачалаСобытия
• заполняет ДатаНачалаПериодаОтсутствия и ДатаОкончанияПериодаОтсутствия
• формирует ПланируемаяДатаВыплаты
• формирует JSON payload для Document_Отпуск

Mapping параметров → полей 1С

Результат

Результат возвращается в переменную процесса:

result.var

По умолчанию возвращается отфильтрованный объект документа:

Ref_Key
Number
Date
Сотрудник_Key
Организация_Key
ДатаНачалаОсновногоОтпуска
ДатаОкончанияОсновногоОтпуска
КоличествоДнейОсновногоОтпуска
Posted
DeletionMark

Фильтрация ответа

Можно задать собственный набор полей:

vacation.select = Ref_Key,Number,Date

Это уменьшает размер переменных процесса и повышает производительность BPMN.

Best Practices

Ограничивайте размер ответа

Используйте $select, $top и $filter.

odata.select = Ref_Key,Description
odata.top = 10

Используйте $select

По умолчанию 1С возвращает все поля объекта.

В специализированных обработчиках UniBPM также используется внутренний фильтр ответа, позволяющий ограничивать поля, сохраняемые в переменные процесса.

odata.select = Ref_Key,Description,Code

Используйте $top

Запрос без ограничения может вернуть тысячи записей.

odata.top = 10

Используйте $filter

Фильтрация должна выполняться на стороне 1С.

odata.filter = Code eq '0000-00028'

Используйте Сотрудник_Key

Многие документы работают с сотрудником, а не с физическим лицом.

Не используйте DeletionMark=true

Это создаст документ сразу помеченным на удаление.

Используйте $format=json

1С может возвращать XML.

$format=json

Проверяйте $metadata

GET /odata/standard.odata/$metadata

Типовые сценарии

Найти сотрудника по табельному номеру

odata.entitySet = Catalog_Сотрудники
odata.operation = QUERY
odata.filter = Code eq '0000-00028'
odata.top = 1

Получить сотрудника по GUID

odata.operation = GET_BY_KEY

Получить последние документы

odata.entitySet = Document_Отпуск
odata.operation = QUERY
odata.orderBy = Date desc
odata.top = 10

Итог

Коннектор onec-odata позволяет легко интегрировать UniBPM и системы 1С.

Основные возможности:

• чтение данных
• создание документов
• обновление объектов
• выполнение выборок

Рекомендуется ограничивать размер ответов и использовать фильтрацию для повышения производительности.