Book a Demo

1C OData Connector

The onec-odata connector integrates Cabinee with 1C systems through the OData API.

The connector lets BPMN processes:

  • retrieve objects from 1C
  • run queries
  • create documents
  • update objects
  • delete objects

The integration is implemented through the Cabinee External Task mechanism.

Architecture

BPMN Process
     │
     ▼
External Task (Cabinee Engine)
     │
Kafka
     │
     ▼
Integration Runtime
     │
     ▼
1C OData API
  1. BPMN calls an External Task\
  2. Cabinee publishes the job to Kafka\
  3. Integration Runtime performs an HTTP request to 1C\
  4. The result is returned to the process

Configuration

The connector is enabled in 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

Parameters

Parameter Description

name logical server name baseUrl OData base URL authType authentication type (BASIC, NONE) username user password password timeoutMs HTTP timeout

Usage in BPMN

The External Task must include the following Extension Properties.

Property Value

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

OData parameters

Core

Property Description

odata.server server name odata.entitySet 1C entity odata.operation operation result.var process variable

Operations

GET_BY_KEY

Retrieve an object by GUID.

Example

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

HTTP request:

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

QUERY

Query objects.

Parameters

Property OData

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

Example

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

CREATE

Create an object.

Example

Create a Vacation document.

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

The payload is passed in a process variable.

{
  "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

Update an object.

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

Delete an object.

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')

Errors

The connector supports two error-handling policies.

Policy Behavior

FAIL_TASK The External Task fails BPMN_ERROR A BPMN Error is raised

Specialized handlers (ZUP)

In addition to the generic onec-odata.execute handler, the platform supports domain handlers that encapsulate the business logic of specific 1C operations.

They simplify BPMN processes and automatically build the payload.

The current version includes the following handler:

Create a Vacation document

Handler:

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

The handler automatically creates a Document_Отпуск document in 1C.

Required parameters

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

Optional parameters

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

Full list of Extension Properties

PropertyDescription
vacation.serverserver name from the application.yaml configuration
vacation.organizationKeyorganization GUID (Организация_Key)
vacation.employeeKeyemployee GUID (Сотрудник_Key)
vacation.startDatestart date of the main vacation (yyyy-MM-dd)
vacation.endDateend date of the main vacation (yyyy-MM-dd)
vacation.registrationPerioddocument registration period
vacation.documentDatedocument date (if omitted, the current time is used)
vacation.absenceStartDatestart date of the absence period
vacation.absenceEndDateend date of the absence period
vacation.reasondocument basis (default: Заявление)
vacation.deletionMarkdocument deletion mark
vacation.paymentLeadDaysnumber of days before the planned payment date
vacation.selectlist of response fields stored in the process variable
result.varprocess variable name for the result
error.policyerror-handling policy (FAIL_TASK or BPMN_ERROR)

Example

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

What the handler does

The handler automatically:

  • calculates КоличествоДнейОсновногоОтпуска
  • sets ДатаНачалаСобытия
  • fills ДатаНачалаПериодаОтсутствия and ДатаОкончанияПериодаОтсутствия
  • builds ПланируемаяДатаВыплаты
  • builds the JSON payload for Document_Отпуск

Parameter mapping → 1C fields

Extension Property1C document field
vacation.documentDateDate
vacation.organizationKeyОрганизация_Key
vacation.employeeKeyСотрудник_Key
vacation.startDateДатаНачалаОсновногоОтпуска
vacation.endDateДатаОкончанияОсновногоОтпуска
vacation.absenceStartDateДатаНачалаПериодаОтсутствия
vacation.absenceEndDateДатаОкончанияПериодаОтсутствия
(calculated automatically)КоличествоДнейОсновногоОтпуска
(calculated automatically)ДатаНачалаСобытия
vacation.reasonОснование
vacation.deletionMarkDeletionMark
vacation.registrationPeriodПериодРегистрации
(calculated automatically)ПланируемаяДатаВыплаты

Result

The result is returned in the process variable:

result.var

By default, a filtered document object is returned:

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

Response filtering

You can specify a custom set of fields:

vacation.select = Ref_Key,Number,Date

This reduces the size of process variables and improves BPMN performance.

Best Practices

Limit the response size

Use $select, $top, and $filter.

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

Use $select

By default, 1C returns all object fields.

Specialized Cabinee handlers also apply an internal response filter that limits the fields stored in process variables.

odata.select = Ref_Key,Description,Code

Use $top

A query without a limit can return thousands of records.

odata.top = 10

Use $filter

Filtering should be performed on the 1C side.

odata.filter = Code eq '0000-00028'

Use Сотрудник_Key

Many documents work with an employee, not with a natural person.

Do not use DeletionMark=true

This would create the document already marked for deletion.

Use $format=json

1C may return XML.

$format=json

Check $metadata

GET /odata/standard.odata/$metadata

Typical scenarios

Find an employee by personnel number

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

Get an employee by GUID

odata.operation = GET_BY_KEY

Get the latest documents

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

Summary

The onec-odata connector makes it straightforward to integrate Cabinee with 1C systems.

Core capabilities:

  • reading data
  • creating documents
  • updating objects
  • running queries

Limit response size and use filtering to improve performance.