Automation configuration
YAML and JSON Reference Guide: schedule, system and service events, sources, destinations, and repeats.
Machine translation
The configuration determines how the automation works. The editor accepts YAML and JSON, checks known fields and does not miss typos in their names.
The configuration size should not exceed 256 KB. Schema versions are supported 1 and 2. Version 2 it is needed to trigger Synchra24 events.
Upper level
| Field | Necessarily | Appointment |
|---|---|---|
version |
yes | Schema version: 1 or 2. Events require 2. |
trigger |
yes | Manual launch, scheduled launch, or event launch. |
source |
for a simple mode without an event | One HTTP source or artifact. For event not used. |
destination |
for the simple mode | A single HTTP destination, artifact, or confirmed chat MAX. |
steps |
for advanced mode | Multiple sources and destinations. |
transform |
no | JavaScript handler settings. |
retry |
no | Repeat sending the data to the destination. |
conditions |
no | Conditions for input data, events, and connected artifacts. |
artifacts |
no | Aliases of the names of the company's artifacts available at all stages of the launch. |
For manual start and schedule, use either a pair source + destination, or an array steps. The input for an event is its payload, so specify only destination or the steps of the appointments. Mix regular fields and steps automation alone is not allowed.
version
version: 1
This field is required and allows the system to interpret the configuration unambiguously after new versions of the format are available.
trigger
Manual start-up
trigger:
type: manual
Automation is performed by pressing the button To run. Fields cron and timezone they are not used in this mode.
Scheduled launch
trigger:
type: schedule
cron: "30 8 * * 1-5"
timezone: Europe/Moscow
| Field | Necessarily | Meaning |
|---|---|---|
type |
yes | manual, schedule or event. |
cron |
for schedule |
Five cron fields: minute, hour, day of the month, month, day of the week. |
timezone |
no | The name of the IANA time zone. By default Europe/Moscow. |
event |
for event |
The exact name of the system event (employee.late) or the full code of the service event (custom.service_42.report_ready). |
Examples of schedules:
| Task | Cron |
|---|---|
| Every day at 00:00 | 0 0 * * * |
| Every day at 08:30 | 30 8 * * * |
| On weekdays at 21:00 | 0 21 * * 1-5 |
| Every hour | 0 * * * * |
| On the first day of the month at 03:15 | 15 3 1 * * |
The schedule is calculated in the specified time zone, and the launch times inside the system are stored in UTC.
A scheduled launch can be configured no more than once every 30 minutes. For example, */30 * * * * Let's say, but */15 * * * * it will be rejected when checking the configuration.
One scheduled or event launch can take no more than 60 seconds. This period includes receiving data from all sources, JavaScript processing, sending to all destinations, delays, and retries. After the limit expires, execution stops and an error appears in the history. The 30 minute interval applies only to the trigger schedule; manual and test launches are not limited to them.
Event Launch
version: 2
trigger:
type: event
event: employee.late
In this mode, the input data is already contained in the event, so source and the steps from kind: source You can't specify it. You only need a handler and one or more assignments. For a complete list of events and an example of conditions, see Synchra24 Event Launch.
For a custom service event, specify the full code from the tab Events For example custom.service_42.report_ready. The event selection from the company's catalog of services is available in the editor. The service itself calls the local name report_ready
through synchra.emitEvent; this call does not create an event definition. Registration, restrictions, and a complete configuration example:
User Service Events.
source
The source is the HTTP address from which automation receives data.
source:
type: http
method: GET
url: https://api.example.com/v1/orders
headers:
Authorization: "Bearer ${secrets.SOURCE_TOKEN}"
Accept: application/json
response:
format: json
encoding: utf-8
| Field | Necessarily | Meaning |
|---|---|---|
type |
yes | For source and destination — http or artifact. |
method |
no | HTTP method. For the default source, it is used GET. |
url |
for HTTP | Absolute address with http:// or https://. |
headers |
no | Up to 50 HTTP headers. You can use secrets in the values. |
body |
no | The body of the source request. Used if the API receives the filter via POST. |
response |
for HTTP | Rules for reading the response. |
If set body, it is sent as JSON. If the receiving API requires the header Content-Type: application/json, add it to headers clearly. For a regular GET, it is better not to add the field.
The source is considered successful only if the HTTP status is between 200 and 299.
response
response:
format: xml
encoding: windows-1251
options:
delimiter: ";"
header: true
| Field | Necessarily | Meaning |
|---|---|---|
format |
no | json, xml, csv, tsv or text. If the field is empty, the format is determined by Content-Type. |
encoding |
no | utf-8 or windows-1251. The default is UTF-8. |
options.delimiter |
no | One separator character for CSV. By default ;. |
options.header |
no | Whether to consider the first line of the CSV as a header. By default true. |
options.root |
no | It is not used for reading; it is used when creating XML. |
More detailed: Data formats.
transform
transform:
type: javascript
timeout_seconds: 2
| Field | Necessarily | Meaning |
|---|---|---|
type |
no | An empty value or javascript. |
timeout_seconds |
no | The function execution limit is from 1 to 5 seconds. The default is 2 seconds. |
If type omitted, the data is transmitted to the destination without JavaScript conversion. If specified javascript, in the tab The handler there must be a function transform(input, context).
destination
The destination determines where the automation transmits the final data: to an external HTTP service, artifact, or a confirmed chat MAX.
destination:
type: http
method: POST
url: https://receiver.example.com/v1/orders/import
headers:
Authorization: "Bearer ${secrets.DESTINATION_TOKEN}"
request:
format: json
encoding: utf-8
| Field | Necessarily | Meaning |
|---|---|---|
type |
yes | For source and destination — http or artifact. |
method |
no | HTTP method. For the default assignment, it is used POST. |
url |
for HTTP | An absolute HTTP or HTTPS address. |
headers |
no | Up to 50 titles. User-defined Content-Type it will be replaced by the type of the selected format. |
request |
for HTTP | Rules for encoding the result. |
body |
no | The explicit HTTP destination body; the transform result is sent without it. |
The assignment is considered successful if the HTTP status is from 200 to 299. The destination response body is not used.
The purpose of artifact
Instead of an HTTP request, the result can be saved to Synchra24.:
destination:
type: artifact
name: warehouse.stock
For this assignment, only type and name. HTTP fields are not specified. More detailed: Automation artifacts.
Sending to MAX via a shared bot
In cloud Synchra24, you can send notifications via a shared platform bot. To do this, open Admin → Automation → Chats MAX. Need a license API integration and the right to manage integrations. If the window says that the bot is not connected yet, keep automation turned off and return to the configuration after the bot is connected by the operator.
Add the bot specified in the window to the MAX group chat or channel with the right to send messages. Send a command in this chat /chatid and copy the received ID. In Synchra24, specify the connection name and ID, and click Send the code to MAX then enter the six digits from the bot message. The code is valid for 10 minutes; after five incorrect attempts, a new one will be required. Up to five code requests per hour are available to the company and to the chat, including unsuccessful submissions. A company can have up to 20 connections.
If the ready-made extension sends notifications to MAX, check the connection in before enabling it. MAX Chats. Installing the extension by itself does not connect the chat. If the list of connections has not loaded, reopen the section; do not create duplicate automation.
For ready-made extensions, leave a name default. If notifications need to go to different chats, create connections with different names and select the desired name in the configuration. You do not need to enter and transfer the token of a common bot to the seller. Connection information is available only within your company.
For an automation developer, the assignment looks like this:
destination:
type: max
name: default
In this assignment, only allowed type and name. The chat ID and token are not specified in the code. The handler returns a simple text of up to 4000 characters. A single row of one or two link buttons is allowed for sections of the current company in the cloud web version.:
function transform(input, context) {
return {
text: 'В Synchra24 появился новый инцидент.',
attachments: [{
type: 'inline_keyboard',
payload: {buttons: [[{
type: 'link', text: 'Открыть инциденты',
url: 'https://app.synchra24.com/activity/' + context.provider_id + '/incidents'
}]]}
}]
};
}
The verification run shows the result of the handler without sending it to MAX. A confirmed chat is required before enabling it. After the actual event, check the message and the automation history. Success means API MAX validation, not human reading. For MAX, resending is not performed automatically even when setting up retry: An undefined response may mean that the message has already been sent. Check the chat before performing any more actions.
To stop notifications, turn off automation or remove its connection in MAX Chats. If this name is used by several automations, sending will stop at each of them. Messages that have already been sent will not be deleted. After removing the bot from the chat, the connection is revoked; to restart, confirm the chat again. Replacing the shared bot also requires a new confirmation. Links to individual box servers are not supported for this purpose.
request
The structure is the same as response:
request:
format: csv
encoding: windows-1251
options:
delimiter: ";"
If no format is specified, the result is sent as JSON.
retry
retry:
attempts: 3
delay_seconds: 10
| Field | Range | Meaning |
|---|---|---|
attempts |
from 0 to 5 | The total number of attempts to send. Values 0 and 1 they mean one attempt. |
delay_seconds |
from 0 to 3600 | Pause between attempts in seconds. |
Repeats refer to sending to HTTP destinations. There are no automatic replays for the general bot MAX. An erroneous request to the source is not repeated during the current launch.
Full YAML example
version: 1
trigger:
type: schedule
cron: "0 2 * * *"
timezone: Europe/Moscow
source:
type: http
method: GET
url: https://accounting.example.com/export/employees
headers:
X-API-Key: "${secrets.ACCOUNTING_API_KEY}"
response:
format: xml
encoding: windows-1251
transform:
type: javascript
timeout_seconds: 3
destination:
type: http
method: POST
url: https://hr.example.com/api/employees/import
headers:
Authorization: "Bearer ${secrets.HR_TOKEN}"
request:
format: json
encoding: utf-8
retry:
attempts: 3
delay_seconds: 15
The same example in JSON
{
"version": 1,
"trigger": {
"type": "schedule",
"cron": "0 2 * * *",
"timezone": "Europe/Moscow"
},
"source": {
"type": "http",
"method": "GET",
"url": "https://accounting.example.com/export/employees",
"headers": {
"X-API-Key": "${secrets.ACCOUNTING_API_KEY}"
},
"response": {
"format": "xml",
"encoding": "windows-1251"
}
},
"transform": {
"type": "javascript",
"timeout_seconds": 3
},
"destination": {
"type": "http",
"method": "POST",
"url": "https://hr.example.com/api/employees/import",
"headers": {
"Authorization": "Bearer ${secrets.HR_TOKEN}"
},
"request": {
"format": "json",
"encoding": "utf-8"
}
},
"retry": {
"attempts": 3,
"delay_seconds": 15
}
}
The formatting button in the editor makes YAML or JSON readable. The download button allows you to select the finished file. .yaml, .yml or .json up to 256 KB in size.
Input artifacts at all stages
Connect artifacts: {settings: service.settings} at the root of the configuration. The values are available in source, conditions, transform and destination. A source type: artifact with name returns the saved value; HTTP supports ${artifacts.settings.field} in the URL, headers, and JSON body. In steps The destination can choose input: ${artifacts.settings}. The terms are used path: artifacts.settings.field or input.field; value it can refer to a connected artifact. In the handler, read context.artifacts.settings.
The input values are loaded once at the start of the startup, including the verification one. If there is no artifact, the launch fails. For events, the source remains the envelope of the event, but the block artifacts it works the same way. The full example, type rules, limitations, and errors are in automation artifacts.
Importing and exporting an Automation ZIP template
In the web administrator, open Automation → From a ZIP template. Download the package and check the parameters shown: template ID and version, launch type, links to secret variables, artifacts, and event. You can change the name before creating it. To import, you need administrator access and a license. API and admin_edit_provider_integrations; the AI license is not needed.
Button Create automation adds the new one turned off record. Existing automations are not replaced, even if the name or ID of the template match. The code, HTTP requests, and import assignments are not executed; the schedule and events do not start launching the pipeline. In the editor, check the addresses, time zone, secret variables, artifacts, and event code of the current company. Then perform the necessary checks and turn on automation separately.
The standard download button in the editor header — Export an Automation ZIP template — packs the current configuration, handler, name and description, including unsaved edits. Exporting does not save changes to automation and does not start it.
Package format
automation.json
pipeline.yaml
transform.js
{
"format": "synchra.automation-template",
"schema_version": 1,
"template": {
"id": "com.example.exchange",
"version": "1.0.0",
"description": "Обмен данными с учётной системой"
},
"automation": {
"name": "Обмен данными",
"description": "Получить данные, преобразовать и сохранить результат"
},
"files": {
"pipeline": "pipeline.yaml",
"transform": "transform.js"
}
}
schema_version — ZIP format version; template.version — version of a specific template; version inside is the YAML version of the pipeline schema. These three values have different purposes. Exporting the editor uses a local identifier local.automation and the version 1.0.0; set your own values for distribution. The identifier is 3-128 lowercase Latin letters, numbers, and dots., _ or -, starts with a letter; the version looks like 1.0.0, the suffix is allowed -beta.1.
automation.name required: from 2 characters to 100 bytes UTF-8. automation.description optional, up to 4000 characters. The template description is up to 2000 characters long. Files in files Required: configuration .yaml, .yml or .json and a separate handler .js. For a pipeline without JavaScript conversion, leave the handler file empty. Field transform.script no need: the code is stored in a separate file, just like in the editor.
Nested directories and one shared folder are allowed with automation.json. The paths are considered relative to the package configuration. You can add README.md, LICENSE and LICENSE.txt; macOS service files are ignored. Other files are not imported.
Accessibility and restrictions
ZIP — up to 1 MiB, automation.json — before 64 KiB, configuration and handler — up to 256 KiB each. In total, up to 32 entries along with catalogs and up to 640 KiB of the total declared unpacked size. UTF-8 is required. Regular ZIP with STORE/DEFLATE without password, ZIP64, multiple volumes and symbolic links are supported. Absolute paths cannot be used., .., backslashes and duplicate names. The actual sizes and CRC are checked, unpacking is limited even if the size in the ZIP directory is incorrect.
Before creation, the system checks the archive and automation settings. If an error is found, no record is created: you can fix the package and select it again without closing the window. A separate YAML or JSON file is loaded with the download configuration button in the editor.
The values of secret variables from the repository, the contents of artifacts, launch history, record and author IDs are not exported. The links remain in the configuration ${secrets.NAME}, artifact names and event code. The shown list of artifacts includes reads and assignments: the input artifact must exist, and the destination artifact will be created by a normal successful launch. Such dependencies are not created automatically. For the service event, check and, if necessary, select the service code of this particular company.
The sources are exported without editing. If the address, company ID, or secret value is written directly in YAML or JavaScript, they will remain in the files. Before transferring the archive, replace the secret values with references to variables. Flag enabled, provider_id, secret values and other fields of the installed record in automation.json not allowed.
ZIP template or store
The ZIP template creates a separate copy of the automation. After importing, you need to configure it for your company; the seller's updates are not linked to such a copy.
If you need ready-made products with publications and updates, use extension store.