Data formats
Work with JSON, XML, CSV, TSV, and text encoded in UTF-8 and Windows-1251, including data from 1C.
Machine translation
Automations can read and create JSON, XML, CSV, TSV, and plain text. The format is configured separately for each source and destination.
The response from a single source should not exceed 5 MB.
JSON
response:
format: json
encoding: utf-8
JSON is converted to regular JavaScript values.:
- The object is in the object;
- array to array;
- strings, numbers, boolean values, and
nullsave the type.
Example of an input response:
{
"items": [
{ "id": 17, "amount": 1250.5 }
]
}
In the handler, the data is available as input.items.
When sending the result in JSON transform it is serialized automatically. No need to call JSON.stringify before returning.
XML
response:
format: xml
encoding: windows-1251
XML is converted to an object. The root element becomes the first key, and the child elements become the fields of the object.
Source XML:
<?xml version="1.0" encoding="UTF-8"?>
<Employees>
<Employee active="true">
<Id>42</Id>
<Name>Анна Смирнова</Name>
</Employee>
<Employee active="false">
<Id>57</Id>
<Name>Павел Орлов</Name>
</Employee>
</Employees>
An object in JavaScript:
{
Employees: {
Employee: [
{
"@attributes": { active: "true" },
Id: "42",
Name: "Анна Смирнова"
},
{
"@attributes": { active: "false" },
Id: "57",
Name: "Павел Орлов"
}
]
}
}
Conversion Rules:
- the attributes are located in
@attributes; - the text of the element is in
#textif the element has both text and child elements.; - one child element becomes an object or string.;
- multiple elements with the same name become an array.;
- numbers and boolean values come from XML in strings, so they need to be explicitly converted.;
- DTDs and XML directives that can connect external entities are prohibited.;
- The maximum nesting depth of XML is 100 levels.
XML from 1C
1C uploads often use Windows-1251 and can return a single element instead of an array when there is only one entry. The secure handler takes both options into account:
function transform(input, context) {
const raw = input.Employees?.Employee;
const employees = Array.isArray(raw) ? raw : raw ? [raw] : [];
return employees.map((employee) => ({
externalId: String(employee.Id || ""),
fullName: String(employee.Name || "").trim(),
active: employee["@attributes"]?.active === "true",
}));
}
Sending XML
request:
format: xml
encoding: utf-8
options:
root: Employees
options.root sets the root element. If the handler result is an object with a single top key, this key is used as the root automatically.
CSV
response:
format: csv
encoding: windows-1251
options:
delimiter: ";"
header: true
| Customization | By default | Appointment |
|---|---|---|
delimiter |
; |
One separator character. |
header |
true |
The first line contains the column names. |
CSV with the title:
id;name;amount
1;Первый заказ;350
2;Второй заказ;420
Converted to:
[
{ id: "1", name: "Первый заказ", amount: "350" },
{ id: "2", name: "Второй заказ", amount: "420" }
]
CSV values are always strings. For calculations, use Number(value).
If header: false, the input data will be an array of strings:
[
["1", "Первый заказ", "350"],
["2", "Второй заказ", "420"]
]
Sending CSV
To send a CSV, the handler must return an array of objects.:
function transform(input, context) {
return input.items.map((item) => ({
id: item.id,
name: item.name,
amount: item.amount,
}));
}
The columns are formed using the keys of the first object. Therefore, it is better to return the same set of fields for all rows.
TSV
TSV works the same way as CSV, but uses a tab character as a separator.
response:
format: tsv
encoding: utf-8
For TSV, the value is options.delimiter not required.
text
response:
format: text
encoding: utf-8
The handler receives the string without additional parsing.
function transform(input, context) {
const lines = String(input)
.split("\n")
.map((line) => line.trim())
.filter(Boolean);
return { lines };
}
When sending in the format text the result is converted to a string.
Automatic format detection
If response.format not specified, Synchra24 analyzes the header Content-Type:
- the value from
json— JSON; - the value from
xml— XML; - the value from
csv— CSV; - the rest of the responses are text.
For predictable operational integration, it is better to specify the format explicitly, especially if the external service returns an incorrect or generic one. Content-Type.
Encodings
Supported:
utf-8orutf8;windows-1251orcp1251.
If encoding omitted, UTF-8 is used.
The encoding is applied after receiving the response and before parsing the format. When sending, the order is reversed: first, JSON, XML, CSV, TSV, or text is generated, then the result is encoded.
How to choose a format
- For modern APIs, use JSON.
- For 1C and older accounting systems, XML, CSV, and Windows-1251 are often needed.
- CSV or TSV are suitable for tabular uploading without complex nesting.
- For a non-standard flat response, use text and parse the string in the handler.
Types of input artifacts
The artifact always stores JSON regardless of the format of the external system. Full substitution ${artifacts.alias.field} it preserves the type of the value in the JSON body; substitution inside the string turns it into text. For URLs and headers, the full value must be a string. For arrays, use a numeric path segment, for example ${artifacts.settings.items.0.id}. Connecting artifacts.