Domain settings (setting)

Description

Degenerate collection of heterogeneous and differently typed domain settings used by processes and microservices working with domain data.
The criterion for a setting to belong to the settings collection is its singleton nature as a value type (as opposed to entities).

Limitations

  • The collection is available in any domain.

Fields

Entity structure
{
  "key": str,
  "value": str
}
Table 1. Fields
Specification Description

Field: key
Mode: in
Type: str
Default: required

Field: value
Mode: in
Type: any
Default: required

Value

Setting keys

Table 2. Setting keys
Specification Description

acme_account_email | domain: master | type: str | default: empty

Email address for notifications about operations of the LetsEncrypt SSL certificate auto-generation service. Filling this field activates the service for all domains. Each domain is then controlled separately (the 'acme_enabled' and 'acme_subdomains' fields).

acme_enabled | domain: any | type: int | default: 0

Flag for the activity of the LetsEncrypt SSL certificate auto-generation service for the domain.
The service requires the 'acme_account_email' setting in the master domain.

On successful generation, the certificate is automatically loaded into 'certificate_pem'.
The certificate is issued for 3 months and renewed automatically.
If the 'certificate_pem' field is filled manually (has no special signature), the auto-generation service is forcibly deactivated.

If the service is inactive, then when a TLS request for the domain arrives, a certificate is searched in the parent domain chain by names (up to the master, if the current domain name is inherited from the master domain name). This assumes that if a certificate exists in the parent domain, the current domain name was added to it as a child (manually or using 'acme_subdomains').
If no certificate is loaded in any parent domain, the certificate from the configuration settings is used (stored on disk at the path set in the configuration).

Certificate validity is monitored by the system state monitoring service.

acme_subdomains | domain: any | type: str | default: empty

List of child domains whose names must be included in the automatically generated LetsEncrypt SSL certificate.

Applied only when the SSL certificate auto-generation service is active ('acme_enabled').

admin_imi_options | domain: master | type: object | default: { …​ }

Settings for the administrator bot: notifications to master domain administrators about system state and commands via messengers. Bot connection (including Telegram, command menu, proxy) is described in the linked article.

A value outside the allowed interval is applied at the nearest interval boundary.

  • im_accounts - identifiers of system messenger accounts of the master domain (im/Accounts collection, isSystem) through which the bot works. Only messengers with incoming authenticity verification are used (Telegram; MAX — polling or webhook over HTTPS with a secret; VK — with client_secret). An empty list means the bot does not work. Set in the administration application: System → Administrator bot.

  • check_interval_sec - system state check period (/system/state), seconds. From 60 to 3600. On each check, for each connected chat it decides whether to send a state file, a reminder, or a normal message.

  • command_expire_sec - maximum command age, seconds. From 10 to 86400. Age is the time from sending the message in the messenger (message time according to messenger data) until processing by the service. Older commands are not executed and are deleted without a response — for example, accumulated while the bot or service was unavailable.

  • command_input_timeout_sec - waiting time for parameters of a command sent without them (selected from the messenger menu), seconds. From 10 to 3600. The bot requests parameters; the next chat message within this time is treated as parameters; another command cancels the wait.

  • send_expire_min - bot message sending deadline, minutes. From 1 to 1440. A message not sent by the messenger within this time (for example, the messenger is unavailable) is deleted and not sent later.

  • reminder_interval_min - reminder period for problems that remain unchanged, minutes. From 0 to 10080; 0 — do not remind.

  • numeric_change_interval_min - minimum interval between state files when only numeric metrics changed (memory, load, queues, etc.) with a transition to another level, minutes. From 0 to 1440. The appearance and change of the problem composition are sent immediately.

  • alive_report_enabled - daily report on service operation. Absence of the report is a sign that intervention is needed.

  • alive_report_times - daily report time: list, minutes from 00:00 in the server local time, from 0 to 1439 (480 - 8:00). The report is sent within a few seconds after each moment.

The parameter replaces the deprecated system_telegram_bot and telegram_bot_token (transferred automatically).

alertcall_defaults | domain: working | type: object | default: { …​ }

Default settings for alerts.
Default phone alert setting keys.

ap_constants | domain: any | type: object | default: { …​ }

Set of domain constants for autoprovision templates (see the ap role).

ap_options | domain: master | type: object | default: { …​ }

Set of options for the autoprovision microservice.

  • masks - File name masks used to recognize MAC addresses in TFTP requests for configuration files. The base format is regular expressions with a {MAC} block replaced by the search template.
    A type (default cfg) can be prefixed, separated by a vertical bar, to distinguish different configuration variants required by the device.
    If a type is specified and differs from cfg, it is added as the final extension when searching for the template file.
    For example, when a Cisco CP-9971 phone requests the file CTLSEP123412341234.tlv, the template type=ctl|CTLSEP{MAC}[.]tlv is found, and the service searches files in descending priority: Cisco CP-9971.tlv.ctl, cisco cp-9971.tlv.ctl, Cisco.tlv.ctl, cisco.tlv.ctl.
    Then follows the description of sipuser.opts.ap_devices.

archive_dialogs_enabled | domain: working | type: int | default: 0

Switch for maintaining the telephone conversation history log (archive_dialogs).
The history contains a link to the conversation recording if it is configured by domain rules and was maintained by the server.

Activating this collection is a necessary element for configuring a standby domain with historical data and conversation recording replication enabled.

audit_options | domain: any | type: object | default: { …​ }

Settings for placing authorization operation information in the data model log.

  • store_logon_users_mode - determines which records to insert into the system/audit/Logons log. Disabled by default (none). Possible variants:

    • 'none' - disable the successful authorization log.

    • 'admin' - add records only for users allowed to modify platform lower-layer collections.

    • 'all' - add a row on successful authorization of any user.

  • store_logon_roles_enabled - determines whether to add the authorized user’s role list to each record. This can be a volume that multiplies the record size. Since user roles are readable from the main collections, the save mode is disabled by default.

  • store_restricted_logon_enabled - determines whether to save information about failed authorization attempts to the system/audit/RestrictedLogons log.

auto_model_db_mode | domain: any | type: str | default: default

Mode for choosing the PostgreSQL model DB name in automatic mode (when no specific connection is specified in storages and 'auto' mode is selected).
Possible values:

  • default - Choose the mode based on the value of the [auto_model_db_mode_default] field set in the master domain.

  • separated - An additional DB is created next to the domain’s main DB.

  • embedded - Model DB schemas are placed in the domain’s main DB.

auto_model_db_mode_default | domain: master | type: str | default: separated

Mode for choosing the PostgreSQL model DB name in automatic mode for all domains where the mode is not overridden by the [auto_model_db_mode] parameter.
Used so that when a domain is created, an additional DB is not hastily created if the number of databases on the DB server must be reduced with many lightly loaded domains.

Possible values:

  • separated - An additional DB is created next to the domain’s main DB.

  • embedded - Model DB schemas are placed in the domain’s main DB.

azure_cloud | domain: working | type: object | default: { …​ }

Connection parameters for Azure.

Secret (apiKey, including in accounts): ciphertext when read; the plaintext value is not returned via API and is decrypted by the service when used (Encryption and keys).

  • speech - connection and authorization parameters for the Azure Speech service. The 'apiKey' and 'region' fields must be filled for correct operation.

The root 'speech' value refers to the 'default' account, which is passed to the component by default.
Thus, if only one account is used for the domain, the 'accounts' field is not required.

The speech object supplies data for connecting to the Azure Speech service:

  • apiKey - authorization API key (SubscriptionId). Created specifically for connecting to the Azure Speech service.

  • uri_asr_short - Optional. URI for connecting to the Azure short audio recognition service. Default: 'https://%REGION%.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1'.

  • uri_tts - Optional. URI for connecting to the Azure speech synthesis service. Default: 'https://%REGION%.tts.speech.microsoft.com/cognitiveservices/v1'.

  • region - required if uri_asr_short is not used. The region value is substituted into the %REGION% macro.

Example 1
{
 "speech": {
  "apiKey": "6nBS8zU7WzGg2VYspx2Ag5G9eavE3eTNV5ByH7",
  "region": "northeurope"
 }
}
Example 2
{
 "accounts": [{
   "My Account B": {
    "speech": {
     "uri_asr_short": "https://northeurope.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1",
     "apiKey": "6nBS8zU7WzGg2VYspx2Ag5G9eavE3eTNN3ByH7"
    }
   },   "My Account C": ...,   ...
  }
 ]
}

They can be specified simultaneously; then the list contains both the 'default' account settings and the settings of the accounts specified in the list.

blf_details_enabled | domain: working | type: boolean | default: false

Switch for the call data detail mode when sending BLF notifications. If disabled, details are not included even if the corresponding rules are configured for subscribers.

blf_external_numbers | domain: working | type: array<str> | default: []

Additional list of external numbers whose state is stored and available for BLF subscription and notifications.
A successful subscription requires permission.

The number must be reachable in routing for the subscribing subscriber.
The subscribed subscriber is notified of a state change when the number exactly matches URI.username of one party of a dialog serviced by the B2B microservice (To and From headers of the SIP INVITE request).
It is important that blf_external_numbers specifies exactly the URI.username number and that the same is specified when configuring the BLF function on the device.

When subscribing to IVR featurecode numbers, the number is substituted with 'ivr-Extension'.

If the specified number is assigned as an internal number of a domain user, it is not treated as external.

The specified external numbers are tracked in all domains to enable subscription to a dialog if the call actually goes through a provider account in another domain.

block_response_malware | domain: master | type: int | default: 1

Operation mode of the function blocking 4xx-6xx responses to SIP requests containing unknown credentials (in particular domain names) in the To field.
Applied in microservices processing SIP signaling: sg, esg, b2b, ivr, conf, prompt, etc.

Possible variants:

  • 0 - responses to failed requests are sent.

  • 1 - responses to failed requests are dropped.

  • 2 - in addition to the previous, the sender IP address enters the dynamic ban filter with parameters 10/10/600 (if 10 failed requests arrive from the IP address within the last 10 seconds, the IP address enters the dynamic ban list for 600 seconds).

Dropping the response is intended to discourage an attacker from brute-forcing options.
Adding to the dynamic ban list is intended to reduce the load of parsing incoming messages.

Even under the conditions, the following do not enter the dynamic ban list:

  • 127.0.0.1,

  • the node’s own local address running the microservice,

  • addresses included in the whitelist of the static border filter.

callscrcode_context | domain: any | type: str | default: str_empty

Service script code for processing call context.
Runs in the master domain simultaneously with any call and is supplied with all callevents events through the script integration mechanism.

The context script is forcibly terminated simultaneously with the call termination.

If the script finishes before the call, events stop being sent.

The script is not started if the field is empty or the code is invalid.

The context script can pass events to context scripts of any domain in the tree, having first started it there asynchronously with the 'Run script' component.

certificate_pem | domain: any | type: str | default: str_empty

Contents of the certificate PEM file (contains both the private key and certificates for domains).

On a TLS request to the system, the certificate of the domain by whose name the connection is addressed is primarily used.

If the domain or setting is absent (empty value), the parent domain certificate is used, and so on up to the master domain.

If no ancestor domain has a configured certificate, the certificate specified in the configuration parameters for the current web server role instance is used.

Secret (private key body): when read, plaintext; via the mcp channel it is masked as *****; not encrypted with the installation key (Encryption and keys).

default_domain | domain: master | type: string | default: str_empty

Domain automatically substituted into the web application when the authorization window is displayed.
If the value is "URL", the DNS domain from the address bar used to load the application is substituted into the domain field.
If empty, the single working first-level domain or the single master domain is substituted automatically.
In other cases, the 'defaultDomain' value from the 'defaults.json' file (/rest/v1/public/resources/defaults.json) is substituted.
Otherwise the field remains empty.

disabled_plugins | domain: master | type: object | default: { …​ }

Allows disabling built-in event processing plugins to save resources. The 'events' list enumerates those to disable:

  • "ccs" — generation of ccsevents events and call state for the ccs Token API;

  • "cti" — generation of CTI integration events (gRPC);

  • "syslog" — sending events to syslog.

The change is applied within 20 minutes.

email_to_fax | domain: working | type: object | default: { …​ }

Parameters for the service that receives an email and sends the attachment by fax.
The service requires the email role.
The service subscribes to email/Messages changes and, when a new email is created, runs the system service script svc_email_to_fax, which requests all unsent messages, dials each of them, and runs the IVR script ivr_email_to_fax to send the fax.

The email must meet the following requirements:

  • the subject contains fax:number, for example fax:1234567

  • exactly one attachment

  • the attachment is in one of the following formats: bmp, jpeg, pdf, png, svg.

The processing result is placed in the statusText field of the email/Messages class; possible values:

  • call_error - failed to dial the number. Treated as unsuccessful; a retry will be made.

  • error_bad_email_format - invalid email format. Treated as an error; no retry.

  • convert_error - failed to convert the attachment to tiff. Treated as an error; no retry.

  • send_error - failed to send the fax. Treated as an error; no retry.

  • sending - fax sending started. Treated as successful; no retry.

  • completed - fax sending completed. Treated as successful; no retry.
    All other statuses are treated as unprocessed.

Available email_to_fax properties:

  • account_id - account identifier (email/Accounts) from which emails are processed.

  • script_user_login - login of the user on whose behalf requests to the email/Messages class are executed.

  • caller_id - number substituted when making the call to send the fax.

  • caller_name - display name (display_name) substituted when making the call to send the fax.

  • enabled - service activity flag.

Example
{
  "account_id": "6dc58a05-0181-858c-e683-00e04c42bef0",
  "caller_id": "fax",
  "caller_name": "fax",
  "enabled": true,
  "script_user_login": "admin"
}

ext | domain: any | type: object | default: {"a":1}

Arbitrary values relating to the domain as a whole, used in plugins and external project settings.
Among others:

  • default_sipuser_noreg_gates - default values for sipuser accounts without registration, applied as the devices.gates field value if the account has an empty value or empty list there.

  • default_provider_srvidxs - default value for provider accounts of the current domain, applied as the serveridxs field value if the account has an empty list there.

fax_to_email | domain: working | type: object | default: {}

Parameters for the fax_to_email feature code.
Available properties:

  • account_id - account identifier (email/Accounts class) on whose behalf the email is sent.

  • receivers - list of fax recipient email addresses.

Example
{
  "receivers": [
    "email1@gmail.com",
    "email2@gmail.com"
  ],
  "account_id": "6dc58a05-0181-858c-e683-00e04c42bef0"
}

https_host | domain: master | type: str | default: empty

DNS name whose access is routed to the web server of the installed system.
Used when HTTP request handling is disabled on web servers (mode).
Applied:

  • when forming access point URLs for product layer microservices.

  • when the web server redirects from HTTP to HTTPS in https+redir mode, if the HTTP access uses a URL with the server IP address.

If the parameter changes while HTTP service is disabled on web servers in the configuration, product microservices or entire nodes with msvc roles must be restarted.
The parameter value is cached for 30 seconds, so wait this time before operations expecting the parameter to take effect.

hunt_sipuser_superstate | domain: working | type: int | default: 0

Switch for linking the 'registered' (registered, available) state of a sipuser account with the 'registered' state of the associated user account for use in the personal queue and hunt group service.

If enabled, the user must be authorized through the application and the WebSocket channel for the resource to become free.

Applied by the 'hunt' microservice when determining resource availability state.

iam_general_svcscript_code | domain: master | type: str | default: empty

Service script code used to identify a user (verify the account password) for the entire system forcibly.

Parameters:

1 – Domain;
2 – Login;
3 – Password.

The script must end with a STOP component and contain a variable named result with the value 1, 0, true, or false.
If for any reason the script fails, does not complete correctly, lacks the specified variable, or the variable has no valid value, the standard user authorization mechanism through the domain center is used. This protects against script failures to avoid loss of access to the system.

The script is created and executed in the master domain. No more than 5 seconds are allotted for execution.
If the script is not set, the standard password verification mechanism in the domain center is used, or the domain service script specified in iam_domain_svcscript_code.

Authorization under the backup master-admin account is performed without running the script.

iam_domain_svcscript_code | domain: any | type: str | default: empty

Service script code used to identify a user (verify the account password) for domain accounts, provided no general identification script is set in the master domain.

Input parameters:

1 – Domain;
2 – Login;
3 – Password.

The script must end with a STOP component and contain a variable named result with the value 1, 0, true, or false.
If for any reason the script fails, does not complete correctly, lacks the specified variable, or the variable has no valid value, the standard user authorization mechanism through the domain center is used. This protects against script failures to avoid loss of access to the system.

The script is created and executed in the domain where authorization is performed.
If the script is not set, the standard password verification mechanism in the domain center is used.
If the general identification script iam_general_svcscript_code is created in the master domain, this script is not applied.

Authorization under the backup master-admin account is performed without running the script.

iam_token_svcscript_code | domain: master | type: str | default: empty

Service script code used to identify a user during external token authorization.
The script is created and executed in the master domain. No more than 15 seconds are allotted for execution.

In particular, this script is used by default as the linking script during OAuth authorization if the OAuth provider entity has login_mode = script and iam_svcscript_code is not set.

Parameters:

1 – Token. If used as the linking script during OAuth authorization, this is the request identifier.
2 - For OAuth linking, the JSON representation of the authorization provider entity.
3 - For OAuth linking, the JSON representation of the current authorization request entity.
4 - For OAuth linking, the remote side’s 'IP address:port' (the authorizing user’s connection).

The script must end with a STOP component and contain a variable named result with the value 1, 0, true, or false.
If authorization succeeds ('result' = 1 or true), the variables named domain and login must be assigned, and a user account with the specified login must exist in the specified domain.
During execution the script may create a user account in the domain (based on authorization in the external system).

External token authorization is performed with the request:

POST /rest/v1/iam/sessions
Content-Type: application/json

{
  "token": "<TOKEN>"
}

billing_options | domain: master | type: object | default: { …​ }

Connection parameters for the billing system and its use.

Billing applies to call legs established with providers (upstream) whose accounts have the corresponding option enabled.
Caller-Id and Called-Id are taken from the external number plan.

The RADIUS protocol is supported (RFC-2865, RFC-2866, RFC-2869, RFC-6929).

Sequence of billing system requests while servicing one dialog:

  1. Before initiating the fork leg, an access request is made.

  2. After the response, an accounting:start request is made.

  3. Periodically during an active dialog, an accounting:interim_update request is made.

  4. When the dialog ends, an accounting:stop request is made.

Billing system access is performed while servicing each dialog by the esg microservice.
If a dialog is between two external subscribers, each leg serviced by an account with billing enabled has its own CallId and is a separate dialog from the billing system’s perspective.

Based on billing system responses, the time allotted to the dialog may be reduced.

Object fields:

  • enabled - global billing switch. Default false.

  • protocol - protocol selection. Possible values: 'radius'.

  • sipcode - SIP code for the rejection message if the call is prohibited by the external billing system. Default 403.

  • statusline - SIP response line for the rejection message if the call is prohibited by the external billing system. Default 'Forbidden'.

  • reason - reason line for the Reason header of the rejection message if the call is prohibited by the external billing system.

  • radius - RADIUS billing system connection options.

RADIUS connection options:

  • access_servers - list of billing system connection points (address:port). Used for Access requests.

  • accounting_servers - list of billing system connection points (address:port). Used for Accounting requests (start, stop, interim_update).

  • attempt_count - number of request retransmission attempts. Used when no response arrives within the set interval. Default 3.

  • request_timeout_ms - timeout for waiting for a response to the sent request. Default 1000.

  • failover_mode - operation mode when there are no responses from the billing system. Variants: 'permit' - continue the call, 'restrict' - block the call. Default 'restrict'.

  • select_mode - connection point selection mode. Variants: 'leader' - in priority order, 'random' - randomly. Calculated independently in each dialog. Default 'leader'.

  • selected_retransmit_count - number of request retransmission attempts to the previously selected connection point before choosing the next one. Default 2.

  • interim_update_interval - accounting:interim_update request period, seconds. Default 60.

  • disable_authenticator_check - switch for checking the Authenticator field in RADIUS server responses.

  • secret - secret string for encrypting values.

  • password - password.

Secret (radius.secret, radius.password): when read, plaintext; via the mcp channel it is masked as *****; not encrypted with the installation key (Encryption and keys).

licowned | domain: any | type: object | default: {}

Composition of quantitative licenses reserved for the domain’s own needs.
Only free domain licenses can be reserved.
The available volume of each license type for reservation in the domain is determined as X = Total – Sub, where Total is the number of licenses received from the parent domain and Sub is the number of licenses passed to child domains.
Reserved licenses cannot be allocated to child domains or reclaimed by the parent domain.
It is impossible to reclaim from reservation the volume of licenses already used by the domain’s internal entities.
More about licenses.

limits | domain: any | type: object | default: {}

Object containing various limits set for the domain.
The following parameters are available:

  • max_simultaneous_call_count - maximum allowed number of simultaneous telephone conversations involving domain subscribers. 0 - no limit. Default: 0.

  • max_call_duration_sec - maximum allowed telephone conversation duration. Value within 10 - 7200. Default 7200.

The following group of parameters allows setting limits on the domain script processing machine.
Each metric can set or remove a limit.
If limits are imposed on this domain in the parent domain (opts), and any of the parameters below would set a lower limit, the value passed from the parent domain is applied.

  • script_pause_between_components - pause in milliseconds between all components of all scripts. It slows down script operation overall and reduces system load. Default: 0 (absent).

  • script_limit_component_count - limit on the number of executed components in one script handler. Includes all nested scripts. When the limit is exceeded, the script terminates and control passes to the post-processing branch with type 'limit exceeded'. Default: -1 (unlimited).

  • script_duration_sec - limit on script handler execution time in seconds. Includes all nested scripts. Default: -1 (unlimited).

  • script_limit_site_count - (not applied) limit on the number of script handlers executed simultaneously on one site. Default: -1 (unlimited).

  • script_allow_global_variables - (not applied) limit on the use of global variables. Default: true (allowed).

meet_config | domain: master | type: object | default: { …​ }

Fragment of the meet server configuration. When changed, it is merged with the configuration created when the meet role starts. Allows applying meet configuration changes that do not require a server restart.

meet_use_system_cert | domain: master | type: boolean | default: false

Flag: when set, certificates for the meet role for wss and turn are determined from the certificate_pem parameter value.
In this case, certificates specified in meet role parameters or in meet_cert_pem and meet_turn_cert_pem are ignored.

The domain for certificate search is determined as follows:

  • for wss from domain.settings.meet_config.era.serverAddress or domain.settings.meet_config.era.defaultDomain (if the first is not set)

  • for turn from domain.settings.meet_config.turn.certDomain

meet_cert_pem | domain: master | type: str | default: str_empty

Contents of the certificate PEM file (contains both the private key and certificates for domains). When specified, the certificate in the meet role certdir parameter is ignored. Applied only when meet_use_system_cert=false.
Secret (private key body): when read, plaintext; via the mcp channel it is masked as *****; not encrypted with the installation key (Encryption and keys).

meet_turn_cert_pem | domain: master | type: str | default: str_empty

Contents of the certificate PEM file (contains both the private key and certificates for domains). When specified, the certificate in the meet role turn_certdir parameter is ignored. Applied only when meet_use_system_cert=false.
Secret (private key body): when read, plaintext; via the mcp channel it is masked as *****; not encrypted with the installation key (Encryption and keys).

mgc_options | domain: master | type: object | default: { …​ }

Configurable common options for 'mgc' microservices.

  • regular_deservice - section for configuring regular preventive media gateway decommissioning.

    • 'enabled' - mode switch. Default true - enabled.

    • 'work_duration_in_hours' - minimum active operation time in hours before a preventive decommissioning decision. From 1 to 744 hours. Default 12 hours.

    • 'allowed_week_days' - list of weekdays on which preventive decommissioning is allowed. An empty list is equivalent to all weekdays. Default - all weekdays.

    • 'allowed_daily_hours' - list of hours of the day when preventive decommissioning is allowed. An empty list is equivalent to all hours of the day. Default - at night from 22 to 5.

  • self_testing - section for configuring automatic media gateway diagnostics.

    • 'enabled' - mode switch. Default true - enabled.

    • 'interval_minutes' - diagnostic interval in minutes. From 1 to 30 minutes. Default 1 minute.

    • 'timeout_deservice' - timeout for waiting for a response to a test request to decide on forced decommissioning. From 1000 to 30000 ms. Default 3000 ms.

    • 'timeout_restart' - timeout for waiting for a response to a test request to decide on a forced unscheduled media gateway restart. From 'timeout_deservice' to 120000 ms. Default 60000 ms.

  • timeout_deservice - maximum allowed media gateway request execution time in milliseconds, after which a forced decommissioning decision is made (it waits for all conversations to finish and does not accept new ones). From 1000 to 60000 ms. Default 5000 milliseconds.

  • trunk_no_voice_stop_after_sec - interval of complete absence of traffic from a device participating in a conversation that automatically terminates the dialog. Default 600 seconds. No traffic during HOLD and CN is not considered a trigger.

Any incorrect value leads to the corresponding default value being applied.

mps_limit_defaults | domain: master | type: object | default: { …​ }

Default value for the maximum allowed message density (messages per second) arriving from an IP address. The default value is applied if no other value is specified for the IP address in the border filter rules.

If the resulting value for the IP address is 0, the limit is considered unset and the anti-spam protection function is disabled.

When anti-spam protection is enabled (a non-zero maximum allowed message density is set for the address per protocol): if the number of messages from the address within a few seconds exceeds the specified density, the address automatically enters a managed ban list for some time, so further messages from it are ignored.

Applicable to facade microservices:

  • value by key 'ws': web server (ws). HTTP API requests, WebSocket connection events, and all WebSocket messages before authorization are counted.

  • value by key 'sip': internal SIP gate (sg) and external SIP gate (esg). All kinds of SIP requests and responses, as well as non-protocol packets arriving at SIP interfaces, are counted.

  • value by key 'ap': autoprovision service (ap). All requests arriving at TFTP and PNP interfaces are counted.

To enable the counter and anti-spam protection, set limits for individual address ranges with border filter rules, and limit the default value based on the majority of scattered single devices not covered by border filter rules.

music_on_hold | domain: working | type: object | default: { …​ }

Groups of hold music that can be assigned to calls by labels.
Keys are arbitrary hold music group tags; values are paths to .wav or .mp3 files, or lists of paths (played in sequence), or directory paths (contents played in random order).

Paths are specified with macro prefixes: :SYNC, :GLOBALSHARE, or :SITESHARE. They may point to sections for the current domain (for example, ':GLOBALSHARE/domains/pbx.incoplax/custom_melodies/2.mp3') or common sections (for example, ':SYNC/common/my_melodies').

For the configured melody to play in a call, add the label 'MOH:<Key>' to the call, where <Key> is the hold music group tag of the current domain.

pgctrl_options | domain: master | type: object | default: { …​ }

Configurable common options for 'middleware' microservices regarding PostgreSQL DBMS replication management.

numbertype_patterns | domain: worker | type: object | default: { …​ }

Number type filter masks.
In particular, 'external' and 'internal' are used when forming forwarding rules by telephone devices.

platform_name | domain: master | type: str | default: COMMUNICATION PLATFORM

Platform name substituted into emails (password recovery, self-registration, invitations, etc.).

product_layer | domain: any | type: object | default: {}

Service information about the product layer installed through the administrator application: version, state, installation date, mode, hash.
These values should not be changed manually to avoid subsequent incorrect operation of the product layer installation and update service.

project_postgresql_connstr | domain: any | type: str | default: str_empty

Connection string to the project PostgreSQL relational DB of the current domain.
Used in scripts to simplify configuration of SQL query components in scripts (the Project item).
The format is specified in the SQL query component description in the Connection string property.
Secret (password in the string): ciphertext when read; the plaintext value is not returned via API and is decrypted by the service when used (Encryption and keys).

quota_options | domain: master | type: object | default: { …​ }

Configuration of keys for allocating access quotas.
These keys can be used in WebSocket connections to limit the number of simultaneous operations, for example those producing a large load.
To apply, use the corresponding WebSocket API * quota.

rec_storagekey_default | domain: worker | type: str | default: empty

Code of the file storage of the current domain (the 'instance' field) for placing call recordings in the domain.
Used by default if no other code is specified in the applied recording rule. See the description of the record rule 'storagekey' property.

redirect_codes | domain: master | type: array<object> | default: []

List of rules mapping specific SIP responses to redirect rule condition types.
The following are applied by default:
decline – 603,
busy – 486,
timeout – 408,
dnd – 404, 480,
error – 0,
other – the remaining codes.

redirect_allowed_masks | domain: working | type: array<str> | default: [*]

List of number masks allowed to be set in the device as the forwarding number.
Applied to devices whose own settings ('opts.redirect_allowed_masks') contain the element '/default' among others.
If a 3xx forwarding to a disallowed number is configured in the device, it is not processed by the server. The information is written to the log.

The following can be used as a mask:

  • constants. For example, 414.

  • the predefined mask * - any number, processed efficiently.

  • special characters. For example 12XX, 8843*.

  • ranges. For example /dia/1240+10.

  • regular expressions. For example /reg/^(7|8)[0-8].*$.

Evaluating a large number of regular expressions reduces overall system performance.

self_register_mode | domain: master | type: str | default: disabled

User self-registration mode.
Value variants:

  • disabled - self-registration is prohibited.

  • master - self-registration is allowed. The list of domains to choose in the registration window is supplied from the master domain setting 'self_register_domains'.

  • auto - self-registration is allowed. The list of domains to choose in the registration window is supplied based on automatic polling of all domains and the 'self_register_allowed' setting value.

self_register_domains | domain: master | type: array<str> | default: []

List of domains supplied in the rest/v1/public/resources/defaults.json request in the 'selfRegisterDomains' field.
Applied when 'self_register_mode' is 'master'.

self_register_allowed | domain: working | type: integer | default: 0

Permission for the domain to allow user self-registration.

self_register_template | domain: working | type: object | default: { …​ }

User account template supplemented to form the account of a self-registering user.
During self-registration the fields 'id', 'name', 'login', 'pwd', 'opts.email', 'opts.self_registered' are added to the template.
All unspecified properties are filled with default values.

serviced_domains | domain: master | type: object | default: { …​ }

Serviced domain filter.
Allows specifying a list of serviced domains for some microservices.
This can be useful in systems with many domains served on few servers.

The domain list contains full domain names of the entire domain tree.
If no value is set for a microservice, or the domain list contains *, the filter is not applied.

Even if the domain tree is split across several microservice instances, they share the same filter.

store_history_options | domain: any | type: object | default: { …​ }

Setting for the mode of saving entity change history in platform static collections serviced by the domain center.

By default, the change history of domain center entities is saved in only one place — the main DB where the entities themselves are stored. This history is readable via '/rest/v1/journal/changes?params={…​}' and used by the administrator application Settings.

Additionally, saving change history to the dynamic data model collection 'platform/log/HistoryChanges', created automatically, can be activated. This collection is used by all dynamic model classes if change history saving is enabled for them. Changes of static collection entities are saved in the same format.

Obviously, both modes can be enabled, or one of them, or history saving can be disabled entirely.

system_state_options | domain: master | type: object | default: { …​ }

Options for the system_state self-diagnostics operation, defining values and thresholds for data entering warnings.

  • log_interval_minutes - interval for polling state and writing the result to the log of the active mware instance. 0 disables regular log writing.

  • svc_script_code - code of the service script executed during the system_state operation. If a script exists, no more than 5 seconds are allotted for execution.
    The script is expected to return the string variable 'result'. If its value is non-empty, it is included in 'system/state' warnings. The reason for unscheduled script termination is also included in warnings.

  • node_startup_sec - node restart warning interval, seconds. Default 60.

  • role_startup_sec - microservice application restart warning interval, seconds. Default 60.

  • backup_warning_timeout_sec - time for placing a warning about a failed backup operation. Default 86400 (1 day).

  • mq_len_pid_threshold - maximum allowed number of unprocessed messages in a process queue. Default 500.

  • mq_len_total_threshold - maximum allowed total number of unprocessed messages in all process queues. Default 1000.

  • mem_available_mb_threshold - minimum allowed available RAM size (free + buffers + caches), megabytes. Default 200.

  • mem_used_percent_threshold - maximum allowed percentage of used memory (allocated - buffers - caches). Default 80.

  • disk_space_work_free_mb_threshold - minimum allowed free space on the working disk, megabytes. Default 5120 (5 GB). This value can raise the threshold compared with the common parameter applied to all available disks.

  • disk_space_total_mb - minimum disk size at which it is analyzed for free space, megabytes. Default 20480 (20 GB).

  • disk_space_free_coeff_threshold - coefficient for dynamically calculating the minimum allowed free disk space threshold relative to its total size. Default 5.

  • disk_space_low_limit_mb - lower limit of the free disk space threshold, below which it does not fall, megabytes. Default 5120 (5 GB).

  • disk_space_high_limit_mb - upper limit of the free disk space threshold, above which it does not rise, megabytes. Default 20480 (20 GB).

  • disk_inodes_total - minimum number of inodes on a disk at which it is analyzed for free available inodes. Default 1310720 (equivalent to 20 GB with standard layout — 4 blocks of 4096 bytes per inode).

  • disk_inodes_free_coeff_threshold - coefficient for dynamically calculating the threshold of free available inodes on the disk relative to the total number on the disk. Default 3.

  • disk_inodes_low_limit - lower limit of the free available inodes threshold on the disk, below which it does not fall. Default 327680 (equivalent to 5 GB with standard layout — 4 blocks of 4096 bytes per inode).

  • disk_inodes_high_limit - upper limit of the free available inodes threshold on the disk, above which it does not rise. Default 1310720 (equivalent to 20 GB with standard layout — 4 blocks of 4096 bytes per inode).

timezone | domain: master | type: str | default: PRODUCT TIMEZONE

Time zone in which the system operates. When changed, each server sets the specified time zone, after which the system must be restarted manually. The time zone is specified in <area>/<location> format (names in the IANA time zone database), for example Europe/Moscow.

user_copy_mode | domain: master | type: str | default: master_only

Global mode for cloning users between domains.
For a user in the master domain, a list of name templates for child domains of arbitrary level can be set to automatically clone the user on every change in the master domain (the 'opts.copy_to_domains' property).
Such users can switch between domains in the client application without entering a password by changing session settings.

The cloning operation is performed on the master site. Accordingly, settings are applied on other sites within 20 seconds (the domain settings synchronization period between sites).

The parameter sets the reverse synchronization mode when users in child domains are changed (or deleted).
The condition is the existence in the master domain of a user with the same identifier as the one changed in the child domain, and the domain name matching the template set for the user in the master domain in 'opts.copy_to_domains'.

  • master_only – changing and deleting such users in child domains is prohibited.

  • sync_oneway – when user properties are changed or the user is deleted in a child domain, the result is applied only in that specific domain until the next user property change in the master domain.

  • sync_bothway – when user properties are changed in a child domain, the operation is duplicated to the master domain, from where, according to child domain name templates, it is distributed to other child domains. In the child domain, changing the login, password, adding or removing the 'admin' role, and deleting the user are prohibited.

  • sync_bothway_accumulate_roles – in addition to 'sync_bothway', accumulates roles. The behavior differs in that roles cannot be removed from the cloned user in a child domain. Consequently, adding different roles in different child domains merges them.

In 'master_only' and 'sync_bothway' modes, regular (once a day) synchronization of cloned user properties from the master to child domains is additionally performed.

user_pwd_policy | domain: master | type: object | default: { …​ }

Global policy for user password complexity.
Applied whenever a user password is changed. The specified password is checked against all regular expressions in the regex_patterns list.
If a mismatch is found, the text from the description field is returned as the error.

Regardless of the configured policy, only passwords shorter than 100 characters and consisting of A-Za-z0-9_-.~! are allowed.

When the policy changes, previous passwords are not reset automatically and continue to work.

worktime_mode | domain: any | type: int | default: 0

Source of the work schedule (weekly schedule and composition of days off and working days).
0 – standard settings;
1 – current domain settings;
2 – inherit from the parent domain.

worktime_periods | domain: any | type: array<object> | default: []

Weekly work time schedule.
Each list element covers a specific segment within the week: from a time on a specific day of the week to a time on another specific day of the week.
The overall schedule is formed from the set of these segments.
Weekly schedule list element.

ws_failover_urls | domain: master | type: array(str) | default: []

List of URLs to alternative system web servers.
Used when generating the connector page.

It is assumed to contain several different connection points to mutually redundant web servers.
If the cluster has several servers and more than one connection point is specified, the user can download the connector from the root client application and subsequently use it to connect to the platform.
The connector discovers an available address and redirects to it.

Example
[
   https://gate1.mydomain:443,
   https://gate2.mydomain:443
]

An HTTP scheme with explicit IP addresses can also be used, but the web softphone in the workstation will work only on the page connected via HTTPS.

xsrv_perfmon_enabled | domain: master | type: bool | default: 0

Switch for the mode that checks communication between servers of one site and logs metric excesses.
Applied on server nodes and logged there.

The '/env/pm_bind_*.log' log records failures when trying to open a socket on the node’s local address. Periodicity 20 ms.
The '/env/pm_ping_*.log' log records excesses of 10 ms in ping operations from the current server to other servers of the current site. Nodes of other servers are polled synchronously with a 10 ms interval between the end of the previous and the start of the next operation.
The '/env/pm_timer_*.log' log records every 10 ms excess in timer operation. The timer is set for 20 ms.

mixed_call_rec_options | domain: any | type: object | default: { …​ }

Server settings for recording in 'mixed_call' mode. An alternative to siprec recording.
Recording to an external server can be enabled in the recording rules of a specific domain (the 'mixed_call_rec' field).
Recording is performed if at least one party of the dialog has a corresponding rule in its domain allowing dialog recording in 'mixed_call_rec' mode.

Recording is performed via one SIP call to each server specified in the 'endpoints' field. SDP describes one mixed stream.
If the server list is empty, recording is performed to the servers specified in the corresponding master domain field.
If servers are not set in either the domain or the master domain, recording in 'mixed_call_rec' mode is not performed.
Recording is also not performed if the object has a mode field with the value disabled at the root level. Default is enabled.

The mode field. Value variants:

  • disabled - recording in mixed_call_rec mode for domain subscribers is disabled. Recording is performed only for cross-domain calls if enabled by another domain’s rules and settings.

  • enabled - recording in mixed_call_rec mode is allowed and performed to the servers specified in the 'endpoints' field of the current value (current domain). By default it contains an empty list, so server settings are determined in the master domain.

  • master - server settings are determined in the master domain. For the master domain this value is equivalent to enabled.

The endpoints field.
Each server is defined by an endpoint, an object with the following fields:

  • enabled - switch. Default true (enabled).

  • ip_address - server IP address.

  • port - server port.

  • transport - transport protocol. Allowed values udp, tcp. Default udp.

  • to_uri - logical name substituted into the To header. Example: <sip:srs@somedomain.local>.

  • from_uri - logical name substituted into the From header. Example: 'Display' <sip:src@mydomain.local>.

  • headers - object with additional non-standard headers. Each key is a header name and its value is the header value.

  • audio_formats - list of codecs offered by the INVITE request from those supported by the platform: exactly they are offered, in list order. If the list is empty, the composition is determined by the payloads_audio_offer parameter in the b2b role configuration. More — Codecs and media negotiation.

When parties from different domains participate in a dialog, each domain supplies its own settings (dialog recording enablement, server list).
No duplicate calls are made.

The call to the recording server is made within 5 seconds. If the recording server fails or does not respond, it is excluded from recording and a corresponding entry is made in the log.

'mixed_call_rec' calls are made immediately after the called subscriber answers and the dialog becomes active.
Like standard recording, each dialog is recorded separately, that is, a separate set of calls to recording servers is formed for each recorded dialog.

Recording can be performed only if media processing is not disabled by configuration in a special way.
Simultaneous recording in different modes can be configured by enabling the corresponding modes in the recording rules.

Since recording is performed by an external system, access to recordings is possible only through it. No special marks are made in native logs.

The 'mixed_call_rec' mode reduces overall system performance because it creates several additional SIP transactions and switches the media context to conference mode, which necessarily entails mixing and transcoding of all RTP streams in both directions.

streamed_call_rec_options | domain: any | type: object | default: { …​ }

Server settings for recording in 'streamed_calls' mode. An alternative to siprec recording.
Recording to external servers can be enabled in the recording rules of a specific domain (the 'streamed_call_rec' field).
Recording is performed if at least one party of the dialog has a corresponding rule in its domain allowing dialog recording in 'streamed_call_rec' mode.

Recording is performed via a pair of SIP calls to each server specified in the 'endpoints' field. The first call transmits the media stream of subscriber A (the dialog initiator), the second the media stream of subscriber B (the called party).
If the server list is empty, recording is performed to the servers specified in the corresponding master domain field.
If servers are not set in either the domain or the master domain, recording in 'streamed_call_rec' mode is not performed.
Recording is also not performed if the object has a mode field with the value disabled at the root level. Default is enabled.

The mode field. Value variants:

  • disabled - recording in streamed_call_rec mode for domain subscribers is disabled. Recording is performed only for cross-domain calls if enabled by another domain’s rules and settings.

  • enabled - recording in streamed_call_rec mode is allowed and performed to the servers specified in the 'endpoints' field of the current value (current domain). By default it contains an empty list, so server settings are determined in the master domain.

  • master - server settings are determined in the master domain. For the master domain this value is equivalent to enabled.

The endpoints field.
Each server is defined by an endpoint, an object with the following fields:

  • enabled - switch. Default true (enabled).

  • ip_address - server IP address.

  • port - server port.

  • transport - transport protocol. Allowed values udp, tcp. Default udp.

  • to_uri - logical name substituted into the To header. Example: <sip:srs@somedomain.local>.

  • from_uri - logical name substituted into the From header. Example: 'Display' <sip:src@mydomain.local>.

  • headers - object with additional non-standard headers. Each key is a header name and its value is the header value.

  • audio_formats - list of codecs offered by the INVITE request from those supported by the platform: exactly they are offered, in list order. If the list is empty, the composition is determined by the payloads_audio_offer parameter in the b2b role configuration. More — Codecs and media negotiation.

When parties from different domains participate in a dialog, each domain supplies its own settings (dialog recording enablement, server list).
No duplicate calls are made.

The call to the recording server is made within 5 seconds. If the recording server fails or does not respond, it is excluded from recording and a corresponding entry is made in the log.

'streamed_call_rec' calls are made immediately after the called subscriber answers and the dialog becomes active.
Like standard recording, each dialog is recorded separately, that is, a separate set of calls to recording servers is formed for each recorded dialog.

Recording can be performed only if media processing is not disabled by configuration in a special way.
Simultaneous recording in different modes can be configured by enabling the corresponding modes in the recording rules.

Since recording is performed by an external system, access to recordings is possible only through it. No special marks are made in native logs.

The 'streamed_call_rec' mode reduces overall system performance because it creates several additional SIP transactions and switches the media context to conference mode, which necessarily entails mixing and transcoding of all RTP streams in both directions.

kafka_mustache | domain: any | type: str | array<object> | default: []

Mustache template for calculating KAFKA message broker connection parameters.
Specified as a string or a list of JSON objects (each bound to a specific site via the site field and a string value via the value field).
Applying the string template to the event JSON object must return a string representation of a JSON object with the fields:

  • endpoints – list of alternative brokers/connection points as objects with host and port keys.

  • topic – topic in the addressed KAFKA instance.

  • security – optional object for connection parameter settings. The following keys are supported:

    • protocol - protocol type. Variants: plaintext, sasl_plaintext, ssl, sasl_ssl.

    • sasl_mechanism - authentication mechanism. Variants: plain, scram_sha_256, scram_sha_512.

    • login - client login.

    • password - client password.

  • partition – optional numeric partition number in the addressed KAFKA instance topic, or the name of the partition calculation module. Predefined modules random and random_by_key. Other Erlang modules with the function partition(Topic::binary(),PartitionCount::integer(),Key::term(),Value::term()) → int() can be added and specified. Default is 'random_by_key', and the final value depends on 'partition_count'.

  • partition_count – optional number of partitions in the addressed KAFKA instance topic. Default 1, and the default partition value is 0.

  • key – optional key by which the partition is calculated. Default str_empty.

  • send_mode – optional mode for placing a record in KAFKA: sync | async | notify. Default async.

  • ensure_topic_mode - optional topic existence check mode. 0 - do not check, send immediately. 1 - read metadata and topic description for checking. Default 1.

Depending on the generated event class, the part of the data between the {{#eventclass}} and {{/eventclass}} blocks is used. If the section for the class is absent, the result is an empty object '{}'.

The event is not sent to KAFKA if the calculated result lacks the required fields, or if no template is found for the site in either the domain or the master domain.
The site field value can be either a site name or a regular expression in the format /reg/…​.

kafka_params | domain: any | type: object | array<object> | default: []

Object with parameters added to the event JSON object to build the mustache template input.
Specified as a JSON object or a list of JSON objects, each bound to a specific site (the site field) and a string value (the value field).
The calculated value is added to the event JSON object in the CLASSNAME field, where CLASSNAME is the value of the class field.
It must be matched with the mustache template calculated for the same domain/site.

The event is not sent to KAFKA if no template is found for the site in either the domain or the master domain.

siprec_options | domain: any | type: object | default: { …​ }

Settings for siprec servers for recording conversations per RFC-7866 and RFC-7865.
Recording via the siprec protocol to external servers can be enabled in the recording rules of a specific domain (the 'siprec' field).
Recording is performed if at least one party of the dialog has a corresponding rule in its domain allowing dialog recording via siprec.

Recording is performed via a siprec call to all servers specified in the 'endpoints' field. The INVITE content, per RFC-7866, contains an SDP section and a call metadata section. The SDP section describes two streams: one transmits subscriber A’s media stream (dialog initiator), the other subscriber B’s (called party).
If the server list is empty, recording is performed to the servers specified in the corresponding master domain field.
If servers are not set in either the domain or the master domain, siprec recording is not performed.
Recording is also not performed if the object has a mode field with the value disabled at the root level. Default is enabled.

The mode field. Value variants:

  • disabled - siprec recording for domain subscribers is disabled. Recording is performed only for cross-domain calls if enabled by another domain’s rules and settings.

  • enabled - siprec recording is allowed and performed to the servers specified in the 'endpoints' field of the current value (current domain). By default it contains an empty list, so server settings are determined in the master domain.

  • master - server settings are determined in the master domain. For the master domain this value is equivalent to enabled.

The endpoints field.
Each server is defined by an endpoint, an object with the following fields:

  • enabled - switch. Default true (enabled).

  • ip_address - siprec server IP address.

  • port - siprec server port.

  • transport - transport protocol. Allowed values udp, tcp. Default udp.

  • to_uri - logical name substituted into the To header. Example: <sip:srs@somedomain.local>.

  • from_uri - logical name substituted into the From header. Example: 'Display' <sip:src@mydomain.local>.

  • headers - object with additional non-standard headers. Each key is a header name and its value is the header value.

  • audio_formats - list of codecs offered by the INVITE request from those supported by the platform: exactly they are offered, in list order. If the list is empty, the composition is determined by the payloads_audio_offer parameter in the b2b role configuration. More — Codecs and media negotiation.

When parties from different domains participate in a dialog, each domain supplies its own settings (dialog recording enablement, siprec server list).
No duplicate calls are made.

The call to the siprec server is made within 5 seconds. If the siprec server fails or does not respond, it is excluded from recording and a corresponding entry is made in the log.

RFC-7865 metadata is generated from the template at /era_sip/priv/siprec/template.xml.
The template contains macros (example: {{some_name}}) replaced with values of the specific dialog:

  • session_id - session identifier, generated automatically. The same value for all siprec servers.

  • call_id - Call-Id header value from the INVITE request initiating the recorded dialog.

  • start_time - recording start time (generated when recording starts, but effectively coincides with the dialog becoming active).

  • a_participant_id - subscriber A identifier (dialog initiator), generated automatically.

  • a_aor - subscriber A logical address, for example sip:user1@some.domain.local.

  • a_dn - subscriber A number, for example 414.

  • a_name - subscriber A full name, for example Ivan Egorov (414). The number is added automatically for internal subscribers.

  • b_stream_id - identifier of the voice stream from subscriber A.

  • b_stream_label - index of the stream from subscriber A for linking with the SDP attribute a=label:1.

  • b_participant_id - called subscriber identifier, generated automatically.

  • b_aor - subscriber B logical address, for example sip:79274137274@some.domain.local.

  • b_dn - subscriber B number, for example 79274137274.

  • b_name - subscriber B name, for example 79274137274.

  • b_stream_id - identifier of the voice stream from subscriber B.

  • b_stream_label - index of the stream from subscriber B for linking with the SDP attribute a=label:1.

Siprec calls are made immediately after the called subscriber answers and the dialog becomes active.
Like standard recording, each dialog is recorded separately, that is, a separate set of calls to siprec servers is formed for each recorded dialog.

Siprec recording can be performed only if media processing is not disabled by configuration in a special way.
Simultaneous recording both in the platform’s normal mode and via calls (in particular siprec) can be configured by enabling the corresponding modes in the recording rules.

Since recording is performed by an external system, access to recordings is possible only through it. No special marks are made in native logs.

Siprec recording mode reduces overall system performance because it creates several additional SIP transactions and switches the media context to conference mode, which necessarily entails mixing and transcoding of all RTP streams in both directions.

survival_options | domain: working | type: object | default: { …​ }

Parameters for configuring domain redundancy on an alternative system instance.
More in the article Domain hot standby.

  • enabled - must be enabled in the settings of both instances. Values: true | false.

  • order - priority for determining master and slave. Must differ from the priority value in the domain setting on the other instance, and from priorities specified in the list of alternative instances. It is recommended that values correspond, that is, the priority in the alternatives list matches the priority of the corresponding other instance, and vice versa. Type: integer.

  • security_key - verification string with an arbitrary key; must match in the settings of both instances. Not encrypted and returned as is. Type: string.

  • token_local - integration channel token in the domain of the current system instance. Used when synchronizing attachment files. Type: string. The value is the plaintext token obtained when creating or reissuing the channel (the token is not returned when reading the channel). Secret: ciphertext when read; the plaintext value is not returned via API and is decrypted by the service when used (Encryption and keys).

  • uris_local - web server URL or a list of URLs of several web servers of the current system instance. Used when synchronizing attachment files. Examples: https://instance1.incoplax.com:443, http://192.168.100.1.

  • alternatives - list of one or more objects describing alternative systems in the redundancy and synchronization group of this domain.

    • name - optional field, used only for logging references to the described alternative instance. Type: string.

    • order - priority for determining master and slave. Must consistently correspond to the root order value in the corresponding alternative system instance. Type: integer.

    • uris - web server URL or a list of URLs of several web servers of the alternative system instance. Used for HTTP and WebSocket connection to the alternative instance web server to determine availability and synchronize data. Examples: https://instance2.incoplax.com:443, http://192.168.100.22. Possible types: string, array of string.

    • token - integration channel token in the domain of the alternative system instance. Used to authorize HTTP and WebSocket connections to the alternative instance web server. The token must have an assigned user with the admin role for full access to settings. Secret: ciphertext when read; the plaintext value is not returned via API and is decrypted by the service when used (Encryption and keys). Type: string.

    • ws_redirect_to - optional field. When filled with valid access URLs to the alternative instance, during the passive state all HTTP authorization requests from users without the admin role are redirected to these addresses of the active alternative instance. Examples: https://instance2.incoplax.com:443, http://192.168.100.22. Possible types: string, array of string.

    • sg_redirect_to - optional field. When filled with valid access URIs to the alternative instance, during the passive state all SIP requests are redirected to these addresses of the active alternative instance. Examples: sip:instance2.incoplax.com:5060, 192.168.100.22:5060, 192.168.100.23. Possible types: string, array of string.

  • activate_delay_sec - optional field allowing the default value to be overridden. Pause before activating the passive instance after detecting loss of the active alternative instance. During the wait, attempts are made to contact the active instance, and if it is found, the timer stops. Default 30 seconds. Decreasing the interval makes sense to increase the availability period, but with the risk of brief simultaneous operation of both instances. Increasing the interval makes sense to reduce false positives on unstable channels and to account for update and restart operations. Type: integer.

  • mode - master behavior mode at startup when an active slave exists - wait for slave deactivation or take over activity with priority. Values: takeover | oneway.

  • name - optional field, not used by the service.

  • sync_settings_mode - settings synchronization mode. Possible values: isolate - do not synchronize settings; oneway - synchronize settings only toward the passive slave; bothway - synchronize settings toward the passive slave and the passive master. Default oneway.

  • sync_history_mode - history synchronization mode. Possible values: isolate - do not download history from the other instance; oneway - download history only from the slave to the master when the master activates, without subsequent subscription to changes; bothway - additionally subscribe the slave to changes of the active master’s history. Default isolate.

  • custom_sync_metadata - optional field for fine-tuning settings and history synchronization modes for specific collections. By default all existing collections are synchronized with partial filtering by values of some entity fields; domain center collections related to individual access settings are selectively excluded from synchronization. Individual collections can be customized.

    • default_enabled_settings - enabled field value for all collections by default (while sync_settings_mode defaults to oneway).

    • default_enabled_history - enabled field value by default (while sync_history_mode defaults to isolate).

    • endpoints_of_settings - object for fine-tuning synchronization of settings collections (domain center collections and data model collections of type 'category'). Each object key is the REST endpoint of a specific collection, and the value is an object of fine synchronization settings for that collection. Keys/REST endpoints not corresponding to the specified collection types are ignored.

      • enabled - collection synchronization handler switch. Values: true | false.

      • filter - additional filter on collection objects; the standard format of the filter parameter of a collection read REST request is used. The system always applies filters to domain center collections on the ext.source and ext.survival_sync fields, and for the domain/settings collection on the key field. Additional filters can only strengthen them. Type: array.

      • order - sorting of entities when reading data; the standard format of the order parameter of a collection read REST request is used. By default sorting by identifier is applied, and in some domain center collections by ext.ct. This is important for the correct order of object creation. Type: array of object.

      • mask - restriction on the composition of collection fields; the standard format of the mask parameter of a collection read REST request is used. Type: array of string.

      • retries - number of iterations when synchronizing the collection in case of errors. For example, it can be used as an alternative to order when working with an inherited class collection. Type: integer.

      • portion_size - non-standard portion size when reading data. Default 1000, but 100 for scripts. It makes sense to base it on the average entity size. Type: integer.

    • endpoints_of_history - object for fine-tuning synchronization of history collections (data model collections of types 'history' and 'transactionlog'). Each object key is the REST endpoint of a specific collection, and the value is an object of fine synchronization settings for that collection. Keys/REST endpoints not corresponding to the specified collection types are ignored.

      • enabled - collection synchronization handler switch. Values: true | false.

      • filter - additional filter on collection objects; the standard format of the filter parameter of a collection read REST request is used. Type: array.

      • use_sync - synchronization operation switch; does not affect changes from notifications based on subscription. Can be used for transactionlog collections in KAFKA without ClickHouse, that is, where data reading is impossible but subscription to the event stream may make sense. Values: true | false.

      • portion_size - portion size when reading data. Default 1000, but 100 for scripts. It makes sense to base it on the average entity size. Type: integer.

speech_analytics_options | domain: master | type: object | default: { …​ }

Speech_analytics mode setting for recorded telephone conversations recorded by the media gateway.

The speech analytics result is placed in the speechinfo field of the callevents.call_rec_links event and also translated into the ccsevents.connection_set_record_info event.

Analytics for each channel includes the talk-over percentage (activity_percent), total talk-over duration (activity_duration_ms), number of speech fragments separated by pauses (activity_fragments), and general information about interrupting the opponent (interrupt _count, _ms, _percent).
When detailed mode is selected (mode=detailed), time-bound lists of speech and interruption fragments are also available.

Speech analytics calculation is performed by the mixer microservice immediately after its main work.
Mixer performance drops by half when speech analytics calculation is enabled.

Speech analytics calculation is activated by the recording rule of the corresponding domain applied to the call.

Possible key values:

  • mode: summary | detailed. Default summary. In detailed mode an additional 'details' section appears listing detected speech fragments.

  • silence-threshold - silence/voice threshold in -dB. Default 40.

  • silence-duration - minimum silence duration in ms. Default 400.

  • voice-duration - minimum voice duration in ms. Default 200.

  • interrupt-offset - minimum interruption offset in ms. Default 1000.

  • interrupt-duration - minimum interruption duration in ms. Effectively the overlap duration (intersection) of two segments. Default 1000.

wakeup_device_options | domain: master | type: object | default: { …​ }

Settings for the push-relay service: waking a sleeping mobile SIP softphone with a push notification on an incoming call (RFC 8599).

The service is used with a native mobile softphone application.
To save battery, the application in sleep mode does not maintain or refresh the connection, does not renew SIP registration, and moreover removes the existing one.
So that the device can still be called, the platform stores the device’s push-relay registration and wakes it with a push notification on a call. The awakened application registers, and the call arrives at the new registration.
Different mobile platforms and applications require different push services and keys; this responsibility is implemented by the push notification sending service.

Device registration

The device passes push parameters in the Contact of each REGISTER:
Contact: <sip:…​;pn-provider=<PROVIDER>;pn-param=<APP>;pn-prid=<TOKEN>>;reg-id=1;+sip.instance="<urn:uuid:…​>", where

  • <PROVIDER> — push service: fcm (usually Android) or apns (usually iOS);

  • <APP> — application: for fcm, the application name (by default matches the Firebase project id); for apns, <TeamID>.<Topic>, for example 7RBDZ62MF9.com.eraplatform.mobile.voip;

  • <TOKEN> — application instance token on the device (percent-encoded);

  • +sip.instance — mandatory device identifier. Without it, push-relay is not created.

The device is stored in telephony/WakeupDevices with the key username + instance; a token change updates the same record.
The MWARE service places a service contact for it in the Registrar. On a call with no live registration of the same instance, B2B sends a push and waits for device registration (default up to 10 seconds).

Deregistration:

  • expires=0 with pn-prid — the device sleeps, push-relay is preserved;

  • expires=0 without pn-prid for its instance — logout, push-relay is deleted (the request is authorized);

  • Contact: * does not affect push-relay.

Push-relay is deleted:

  • after 30 days without SIP registrations;

  • immediately if the push service confirmed the application instance does not exist (FCM 404 UNREGISTERED, APNs 410);

  • after a series of failures without subsequent registrations: temporary push service refusals (5xx, 429) or no device registration until the wait after a sent push ends. Deletion occurs after three or more failures, depending on their number — 2-14 days after the first.

Configuration errors (no application settings, push service 4xx, gateway unavailable) do not increase the failure counter.
On a confirmed push failure, the wakeup call branch ends immediately; if there are no other responses, 480 is returned to the caller.
If the push service did not respond within the wait, the push may have been delivered — waiting for registration continues.

Modes

The mode field:

  • local — sending is performed independently, application keys are required;

  • remote (any value other than local) — proxy mode: the request is passed to an external push-relay gateway (vendor.incoplax.com or another); the gateway sends using its own keys.

Remote (proxy) mode

Gateway responses: 202 — sent, 410 — application instance does not exist, 503 — temporary push service failure, 504 — push service did not respond in time, others — configuration error.

Local mode

The fcm and apns sections correspond to <PROVIDER>; keys inside are <APP> (for apns, the team key <TeamID> is also allowed).
The record is mandatory: applications without a record are not serviced.

fcm.<APP> record parameters (all optional):

  • projectId — Firebase project id. Default <APP>;

  • privateKeyPath — Firebase service account key. Default :SYNC/common/wakeup/fcm/<projectId>/key.json;

  • sendUrl — Default https://fcm.googleapis.com/v1/projects/<projectId>/messages:send.

  • expires — push notification lifetime in seconds for resending. Default 5. More than 10 seconds makes no sense because a specific call waits for registration with this timeout.

The platform obtains the FCM access token itself: a JWT signed with the service account key is exchanged at the token_uri from the key.

apns.<TeamID> and apns.<APP> record parameters (the application record supplements the team record):

  • keyId — APNs Auth Key identifier (Apple Developer Portal). Required;

  • privateKeyPath — APNs Auth Key (.p8). Default :SYNC/common/wakeup/apns/<TeamID>/key.p8;

  • sendUrl — Default https://api.push.apple.com/3/device/DEVICE_TOKEN, where DEVICE_TOKEN is the device token macro. For debug builds — api.sandbox.push.apple.com;

  • aps — the aps object in the push body. Default {}.

  • expires — push notification lifetime in seconds for resending. Default 5. More than 10 seconds makes no sense because a specific call waits for registration with this timeout.

The platform signs the APNs access token (JWT ES256) itself with the APNs Auth Key.

TeamID and apns-topic are taken from <APP>; the push type is voip if the topic ends with .voip, otherwise alert.

To receive requests from other platforms in local mode, fill the 'telephony/WakeupClients' directory.

snmp_options | domain: master | type: object | default: { …​ }

SNMP trap configuration.
The system notifies via SNMP version 2c traps about events of certain types occurring on the current site.
MIB file location: :SYNC/common/snmp/ERA-MIB.mib
IANA Enterprise number: 60663.
Traps are sent to the standard port 162.

'ip' and 'community' define the monitoring node to which traps are sent.
Secret (community): when read, plaintext; via the mcp channel it is masked as *****; not encrypted with the installation key (Encryption and keys).
'enabled' - trap sending mechanism switch.

Notifications are sent according to the type and level filter. An event is not sent if:

  • the event type is contained in the 'excluded_types' field;

  • the 'types' field does not contain '*' or the event type;

  • the type logging level is lower than the configured one (index value higher).

Logging levels - 'level':

  • emergency (0)

  • alert (1)

  • critical (2)

  • error (3)

  • warning (4)

  • notice (5)

  • info (6)

  • debug (7)

Event types - 'types', 'excluded_types' (in parentheses - logging level and MIB event type):

  • syslog_up (info; systemAlert) - syslog agent service restarted.

  • node_down (warning; nodeDown) - node communication lost, generated 5 seconds after communication loss.

  • node_restart (notice; nodeRestart) - node restarted within 5 seconds after communication loss.

  • node_up (info; nodeUp) - node started.

  • role_down (critical; roleDown) - role became unavailable, generated 10 seconds after communication loss if no instance is available on the site.

  • server_down (error; serverDown) - server communication lost, generated 10 seconds after loss of communication with the server root configuration node.

  • mg_queued (notice; mgAlert) - media gateway queued for decommissioning due to an error or response timeout.

  • mg_deserviced (notice; mgAlert) - media gateway decommissioned.

  • mg_killed (info; mgAlert) - media gateway killed by the system.

  • mg_cold_boot (warning; mgAlert) - media gateway started in cold boot mode.

  • mg_disconnected (warning; mgAlert) - media gateway communication lost, generated by the controller 5 seconds after disconnect.

  • mg_connected (notice; mgAlert) - media gateway connected.

  • db_connected (info; dbAlert) - persistent DB connection established successfully. Role: domain center. The domain is indicated in the message text.

  • db_connect_error (error; dbAlert) - DB connection error. Role: domain center. The domain is indicated in the message text.

  • db_loaded (info; dbAlert) - domain loading from the DB completed successfully. Role: domain center. The domain is indicated in the message text.

  • db_load_error (error; dbAlert) - domain loading from the DB failed. Role: domain center. The domain is indicated in the message text.

  • backup_done (info; backupAlert) - backup completed.

  • backup_error (alert; backupAlert) - backup failed.

  • admin_logon_local (notice; auditAlert) - login from an administrator account (user with 'admin' and/or 'crud' roles) with local password verification (without external authorization), a new HTTP or WebSocket session created, or a single request performed. domain, login, peer are passed.

  • user_logon_local_restricted (notice; auditAlert) - authorization attempt recorded due to an incorrect password during local verification (without external authorization). domain, login, peer are passed.

  • sip_dialog_crashed (warning; systemAlert) - SIP dialog servicing process failed. Parameters contain the initiator leg CallId.

  • media_unavailable (error; systemAlert) - SIP server failed to reserve a media context on the media gateway. Parameters contain the initiator leg CallId.

  • system_state (info | alert | emergency; healthInfo) - regular message (every 5 minutes unless configured otherwise) with the system self-diagnostics result (/api/monitor/v1/system/state). 'key': 'status', 'value': 'ok', 'alert', 'error'. For an 'alert' notification the 'message' field contains the list of keys from the self-diagnostics result. The analyzed key list can be reduced by specifying an additional 'system_state_excluded_keys' key in the options with a list of keys whose values are not analyzed when determining the message type ('ok' or 'alert').

  • certificate_expires (warning | critical; certificateExpiresAlert) - notification about SSL/TLS certificate expiration. Generated for each certificate that has expired or expires within the next 2 weeks. Generated no more than once per day between 08:00 and 10:00 UTC. The 'message' field contains the notification text; 'key' and 'value' point to the certificate itself - domain or configuration, and the domain or path.

  • sip_provider_state_changed (info; sipProviderAlert) - notification about a change in the telephony provider connection state. Generated from registration/re-registration and ping results. Possible values: 'available', 'unavailable', 'unknown'.

  • sip_providers_available (info; rateInfo) - regular message (once per minute) reporting the total number of active (connected) telephony providers. Successfully registered accounts with a successful ping, as well as accounts without registration and without configured ping, are included.

  • sip_cps_rate (info; rateInfo) - regular message (once per minute) reporting the average cps value rounded down to an integer. All calls passing through B2B except those initiated by service services are counted separately.

  • sip_route_fin_rate (info; rateInfo) - regular message (once per minute) reporting the average number of unsuccessful call routing attempts per minute. Includes all calls arriving at B2B that ended at the routing stage.

  • sip_devices_registered (info; rateInfo) - regular message (once per minute) reporting the current number of all registered SIP devices in all domains without grouping by account.

  • users_registered (info; rateInfo) - regular message (once per minute) reporting the current number of connected users (active WebSocket connection to the web server) in all domains, grouped by account.

Other parameters:

  • 'system_state_interval_min' - sets the interval in minutes for sending the healthInfo (system_state) trap. Default 5.

  • 'system_state_excluded_keys' - sets the filtering mode for healthInfo tests. Tests listed in the list are performed but do not affect the signal type decision.

  • 'rate_interval_min' - sets the interval in minutes for sending all rateInfo streaming trap events. Default 1.

record_asr_options | domain: master | type: object | default: { …​ }

Connection settings for the recorded conversation transcription service.

Secret (apiKey, secretKey, auth_data, client_secret of a SERVER object): ciphertext when read; the plaintext value is not returned via API and is decrypted by the service when used (Encryption and keys).

Supported:
* VOSK service over gRPC (can be installed in a Docker container on one or several servers).
* WHISPER service over HTTP (can be installed in a Docker container on one or several GPU servers).
* Yandex Cloud SpeechKit service over HTTP.
* Sber SaluteSpeech service over gRPC (cloud and on-premise).

All conversations subject to automatic recognition after completion, based on recognition rules in the respective domains, are queued and processed sequentially during the configured daily time interval.
By default the queue is processed in one thread unless otherwise specified in thread_count.

If a conversation was not configured for transcription but was configured for recording and saved in the archive, transcription is available on demand (HTTP REST API or WEBSOCKET CCS API).

Transcription logging is performed on the active mware microservice node with the marker 'rec_asr'. For debugging, use TRACE or DEBUG logging level.

Value format
{
  "type": ...,
  "servers": [
     <SERVER>,     ...
  ],
  "thread_count": ...,
  "utc_hours": [FromHour, ToHour]
}
  • type - can be 'yandex', 'sbersalute', 'whisper', or 'vosk'.

  • servers - list of objects with connection parameters to the speech recognition server/service. Key content differs by type.

  • thread_count - number of simultaneous handler threads for the conversation recognition job queue.

  • utc_hours - list of two numbers: the start hour and end hour of work with the conversation recording queue. By default time is unlimited.

SERVER object fields for type='yandex':
When using the settings.yandex_cloud setting, specify account_id.
When specifying connection parameters directly, specify:
* speech object: apiKey, uri_tts, uri_asr_short, uri_asr_long, uri_asr_long_response.
* storage object: bucket, keyId, secretKey for uploading long audio.

SERVER object fields for type='sbersalute':
When using the settings.sber_salute setting, specify account_id.
When specifying connection parameters directly, specify a speech object with:
* mode - cloud or onprem.
* auth_data - Authorization data (cloud).
* client_secret - client secret (cloud).
* cert_oauth - OAuth certificate path (cloud).
* endpoints - array of objects with uri_asr and cert.
* model, language, enable_profanity_filter, no_speech_timeout, max_speech_timeout, force_cyrillic, insight_models, hintsWords, hintsEnableLetters, hintsEouTimeout.

The speech object contains service parameter values that the component sets when executing ASR requests from a script. When using the service for transcribing recorded conversations, parameters should be set here directly. Some have default values.

SERVER object fields for type='whisper':
* uri - transcription task submission URL.
* uri_get_task_result - task result URL with the %TASK_ID% macro.
* headers - optional list of HTTP request headers.
* timeout_sec - optional total timeout.
* timeout_headers_sec - optional timeout until response headers are received.
* timeout_chunks_sec - optional timeout until each next result chunk.

The whisper adapter sends the request asynchronously and then periodically polls for the result.

SERVER object fields for type='vosk':
* host - VOSK server IP address.
* port - VOSK server port.

The default timeout for synchronous requests is 1 hour.

For streaming schemes where response headers are returned immediately and content arrives in parts, the wait timeout can be reduced by additionally setting timeouts until response headers are received and until each next response content portion.
This can prevent long waiting/hanging on whisper server failures or unavailability, but requires streaming output of result portions as they become ready and a concatenable output format (a standard JSON object as content obviously creates a problem).

For polling schemes the timeout is the maximum result wait time, and the task itself is serviced asynchronously — the platform periodically polls for result readiness. The timeout of such requests is 10 seconds, and the interval between them is dynamically adjusted to the source audio recording size; timeouts are set automatically.

The examples use a TLS certificate placed in the :SYNC directory of the corresponding domain. This is an alternative, more compact way to specify a certificate, but the full PEM file body can also be placed instead of the specified path.

Storage setting keys

Table 3. Storage setting keys
Field Storage type Description

bucket

s3

Required field. Bucket name.

key

s3

Required field. Public key.

secret

s3

Required field. Secret key.

region

s3

Region for AWS S3 Cloud for automatic endpoint detection.

endpoint

s3

Non-standard endpoint for connection, alternative to automatic detection based on region

prefix

s3

Placement path in the bucket.

host

clickhouse

Required field. Access point IP address.

login

clickhouse

Required field. Login.

password

clickhouse

Required field. Password.

port

clickhouse

Non-standard access point port, different from 8123.

database

clickhouse

Non-standard database name, different from "default".

Weekly schedule list element

Table 4. Weekly schedule list element
Field Value Description

daystart

1 – 7

Day of week when the segment starts (1 – Mon, 7 – Sun)

daystop

1 – 7

Day of week when the segment ends (1 – Mon, 7 – Sun)

timestart

0 – 1440

Start time of the segment within the day, in minutes

timestop

0 – 1440

End time of the segment within the day, in minutes

Default phone alert setting keys

Table 5. Default phone alert setting keys
Field Default Description

attemptcount

1

Maximum number of attempts per subscriber

attempttimeoutsec

10

Pause after a failed subscriber call, in seconds

callerid

"100"

Number/username of the initiator when calling subscribers (SIP)

calltimeout

30

Subscriber call timeout

trunkcount

1

Maximum number of trunks for the alert

See also

Logical roles

  • mdc and sdc store and provide domain settings to processes, and inherit parent domain settings.