1C:Enterprise

A business process in CityScreen Deals can read records from a 1C:Enterprise base and create or change records in it, through the standard OData interface that the base publishes. A typical exchange reads the legal entities («Контрагенты») and their contracts into Deals directories, creates the invoices («Счёт на оплату покупателю») in 1C from the deal’s proposals, and reads the incoming payments back.

The connector carries the requests and holds no accounting rules. What a process reads, how it matches records, and which amounts and VAT it sends are written in the process’s script tasks.

This function is licensed. If your organization’s license does not include it, contact CityScreen.

Before you start

The 1C administrator publishes the standard OData interface of the base and chooses which objects it publishes. A process reads and writes only the published objects.

You need the address of the publication and a 1C user that may read and change those objects.

Connection accounts

An organization keeps one or more connection accounts, one for each 1C base it works with. A script task names the account it uses, and the login and password stay in the account.

  1. Open Settings → 1C.

  2. Click Add account and fill in the fields.

  3. Save, then click Test connection on the account’s row.

Field Meaning

Name

How a script task refers to the account. The name is unique within the organization, regardless of letter case.

Base URL

The address of the 1C publication, such as https://1c.example.com/accounting. CityScreen Deals appends /odata/standard.odata itself. The host must be reachable from the internet. If your 1C base is reachable only inside your own network, contact CityScreen support.

Login, Password

The 1C user the requests are made as. The password is never shown again after it is saved. When you edit an account and leave the password empty, the stored password is kept.

Timeout, s

How many seconds a request waits for 1C to answer, from 1 to 600. The default is 60.

One 1C base often holds several of your legal entities. The 1C organization is therefore a field of each record a process sends (Организация_Key), and an account names no organization.

Test connection checks the connection and shows the result:

  • the connection works;

  • 1C does not answer: check the host, the port and the network;

  • 1C refused the login or password;

  • there is no OData publication at this address;

  • 1C answered with another error.

Each failure also shows the text of the 1C answer, or of the network error when 1C did not answer.

The 1C tab is shown to employees whose role holds the permission 1C accounts and whose organization has the function. The permission has the scope Any only, and it offers Create, View, Edit and Delete. View shows the accounts, Create adds an account and tests the connection, Edit changes an account, and Delete removes it. See Roles & Permissions.

A script task that names a deleted account fails, so rename or delete an account only together with the processes that use it.

Calling 1C from a script task

A script task reaches 1C through the object oneC. Every call names the connection account and the OData entity set, such as Catalog_Контрагенты or Document_СчетНаОплатуПокупателю. The call runs for the organization that owns the process.

Call Result

oneC.list(account, entitySet, query)

The records the query selects, limited by its top and skip.

oneC.listAll(account, entitySet, query)

Every record of the list, sorted by the orderby of the query, or by Ref_Key when the query gives none.

oneC.get(account, entitySet, ref)

One record by its reference (Ref_Key).

oneC.create(account, entitySet, fields)

Creates a record and returns it as 1C stored it.

oneC.update(account, entitySet, ref, fields)

Changes the given fields of a record and returns the record.

The query of a list is an object with any of the keys filter, select, orderby, top and skip. They carry the OData options $filter, $select, $orderby, $top and $skip. A key with another name fails the call, and no request is sent. listAll ignores top and skip.

Records come back as objects whose fields are read by their 1C names, such as record.Ref_Key or record.ИНН, and lists are read with size() and get(i). A tabular part of a record, such as the goods of an invoice, is an array of objects inside the record.

Posting a document and marking a record for deletion are field changes in 1C: oneC.update with {Posted: true} or {DeletionMark: true}.

Example: an invoice for a contractor found by its taxpayer number

The script finds the contractor by its taxpayer number, creates an invoice for one service, and stores the 1C number and reference in process variables for the next steps. The account is named Main base, and the process variables inn, organizationRef, contractRef, serviceRef and amount were set by earlier steps. A script writes a process variable with execution.setVariable(name, value).

if (!/^[0-9]+$/.test(inn)) {
    throw new Error("The taxpayer number must hold digits only: " + inn);
}
var found = oneC.list("Main base", "Catalog_Контрагенты", {
    filter: "ИНН eq '" + inn + "'",
    select: "Ref_Key,Description"
});
if (found.size() !== 1) {
    throw new Error("Expected one contractor with the taxpayer number " + inn + ", found " + found.size());
}
var contractor = found.get(0);

var vatRate = 22;
var vat = Math.round(amount * vatRate) / 100;

var invoice = oneC.create("Main base", "Document_СчетНаОплатуПокупателю", {
    Date: "2026-12-01T00:00:00",
    Организация_Key: organizationRef,
    Контрагент_Key: contractor.Ref_Key,
    ДоговорКонтрагента_Key: contractRef,
    СуммаВключаетНДС: false,
    СуммаДокумента: amount + vat,
    Товары: [{
        LineNumber: "1",
        Номенклатура: serviceRef,
        Номенклатура_Type: "StandardODATA.Catalog_Номенклатура",
        Количество: 1,
        Цена: amount,
        Сумма: amount,
        СтавкаНДС: "НДС22",
        СуммаНДС: vat
    }]
});

execution.setVariable("invoiceNumber", invoice.Number);
execution.setVariable("invoiceRef", invoice.Ref_Key);

The fields an invoice needs, and values such as the VAT rate НДС22, depend on the configuration of the base and on the date. Read one existing invoice with oneC.get or oneC.list to see the fields and values your base uses.

Request journal

Every request to 1C and its response are recorded in the organization’s journal. A request that was sent again appears as several entries.

An entry holds the account, the method, the URL, the response status, the duration, the business process instance that made the call, the request and response bodies, and the error text when there was no response.

The journal is read through the REST API with the permission 1C request journal, which has the scope Any only and offers View. The entries hold the data that processes exchanged with 1C, so grant the permission only to employees who may see that data.

Request Result

GET /one-c/journal

Entries of the organization, newest first, in pages (page, size). Filters: accountId, processInstanceId, and status with the value success (a 2xx response) or error (no response, or another status). The bodies are left out of the list.

GET /one-c/journal/{id}

One entry with the request and response bodies.

To find out what a failed instance sent and what 1C answered, filter the journal by the instance’s ID.

When a call fails

A call fails when 1C answers with an error status or gives no answer within the account’s timeout. The script task then raises an incident on the process instance, with the error text that 1C returned.

A script task that called 1C is not run again on its own when it fails, so nothing reaches 1C a second time until you recover the instance.

oneC.create is sent once and is not repeated. Within one call, a read or a change may be sent to 1C more than once, and every attempt is a separate entry in the request journal.

When oneC.create fails, check in 1C whether the record was created anyway, because a script task that runs again sends the create again. The request journal, filtered by the instance ID, shows the request that was sent.

A call also fails, with no request sent, when the organization has no account of the given name, when a reference is not a GUID, or when the query has a key the call does not know.

After the cause is fixed, recover the instance as the section "Recovering from a failure" of Instances & Incidents describes.

How 1C answers

A script receives what 1C returned, unchanged. These points of the 1C interface affect how a script is written:

  • A reference in the header of a document is a field with the suffix _Key, such as Контрагент_Key. A reference in a tabular part is a field with the name of the attribute and a second field with the suffix _Type, such as Номенклатура and Номенклатура_Type.

  • Tabular parts come inside the record when the query gives no select. 1C answers $expand on a tabular part with an error (501).

  • Pages read with skip and no orderby come in no stable order and repeat or miss records. Give an orderby whenever you page with list; listAll returns every record once without an orderby.

  • A field that can hold references of several types is filtered with cast, such as cast(ДокументОснование,'Document_СчетНаОплатуПокупателю') eq guid'<reference>'.

  • A record created through OData is written without the calculations that the 1C form runs. Send the amounts and the VAT in the request.

Related pages