Functional group (sipkit)

Table of Contents

Description
Limitations
Fields
Types of groups
Additionally
- Filter operation modes
See also
- API
- Logical roles

Description

Defines a group of SIP user accounts whose call is serviced by the group algorithm.

The following feature types are available: forwarding group, failover group, call option setting group, parallel call group, and chief-secretary group.

Limitations

The collection is not available in the master domain.

Fields

Entity structure

{
  "id": uuid,
  "name": str,
  "type": str,
  "enabled": bool,
  "cascade": bool,
  "priority": int,
  "details": object,
  "opts": {
    "title": str,
    "comment": str
  },
  "ext": {
    "ct": date,
    "lwt": date
  }
}

Description of the specification’s characteristics

Table 1. Fields
Specification	Description
Field: `id` Mode: `inout` Type: `uuid` Default: generated	Identifier. Can be specified at creation, otherwise generated by the system.
Field: `name` Mode: `in` Type: `str` Default: required	Group name. Displayed during tracing.
Field: `type` Mode: `in` Type: `str` Default: required	Group Type. Specific settings are set for each type in the field 'details'. The following types are available: `redirect` - call forwarding. `reject` - call rejection. `options` - setting the call parameters. `parallel` - call parallelization. `chief` - chief secretary. `custom` - is used to implement the project logic.
Field: `enabled` Mode: `in` Type: `bool` Default: true	Group switch.
Field: `cascade` Mode: `in` Type: `bool` Default: `false`	Cascading mode switch. If off, when a higher priority group is applied to the same number, a lower priority group of the same type will not be applied to the same number. However, if forwarding or paralleling occurs while the group is being applied, the application of groups of this type to other numbers is not blocked.
Field: `priority` Mode: `in` Type: `int` Default: 1000	Group Application Priority.
Field: `details` Mode: `in` Type: `object` Default: ``	Typed object. If typed settings are not specified when creating a group, they are formed and filled with default values. More information in GroupTypes.
Field: `opts` Mode: `in` Type: `object`	Composite field
Field: `opts.title` Mode: `in` Type: `str` Default: empty	Arbitrary header
Field: `opts.comment` Mode: `in` Type: `str` Default: empty	Arbitrary comment
Field: `ext` Mode: `inout` Type: `object`	Composite field allowing to extend the composition with arbitrary keys and values
Field: `ext.ct` Mode: `out` Type: `date` Default: generated	Object creation time
Field: `ext.lwt` Mode: `out` Type: `date` Default: generated	Time of last modification of the object

Types of groups

Depending on the group type set, a special 'details' parameter is set and the corresponding logic is implemented during the call.

Forwarding group (redirect)

Call Forwarding Group.

The 'filter_from' filter is applied to the number of the original originating caller, excluding call forwarding and transfers. The number of the call forwarder can be filtered by the field 'filter_by'.

Table 2. Parameters
Field: `filter_from` Mode: `in` Type: `str` Default: `*`	Source number filter mask. The result of the modification by the routing rules applied in the previous steps is checked. Initially the source number from the username field of the Referred-By header, and in its absence from the From header, SIP-request INVITE, or the result of a more complex definition of the initiator subscriber number (e.g. sipuser phonenumber, the result of applying sipuser extension, callerid to esg conversion rules, etc.) is checked. Filter operation modes.
`Field: filter_by Mode: in Type: str Default: *`	Mask-filter the number of the caller who forwarded the call. Filter operation modes.
`Field: redirect_number Mode: in Type: str Default: empty`	Forwarding number.

Example

{
  "filter_from": "*",
  "filter_by": "*",
  "redirect_number": "122"
}

Failure Group (reject)

Call Denial Group.

Table 3. Parameters
Field: `filter_from` Mode: `in` Type: `str` Default: `*`	Source number filter mask. The result of the modification by the routing rules applied in the previous steps is checked. Initially the source number from the username field of the Referred-By header, and in its absence from the From header, SIP-request INVITE, or the result of a more complex definition of the initiator subscriber number (e.g. sipuser phonenumber, the result of applying sipuser extension, callerid to esg conversion rules, etc.) is checked. Filter operation modes.
`Field: filter_by Mode: in Type: str Default: *`	Mask-filter the number of the caller who forwarded the call. Filter operation modes.
`Field: sip_code Mode: in Type: int Default: 403`	Response code.
`Field: sip_reason Mode: in Type: str Default: Rejected by kit`	Reason for rejection.

Example

{
  "filter_from": "*",
  "filter_by": "*",
  "sip_code": 603,
  "sip_reason": "Some reason"
}

Call option setting group (options)

The group generates call option changes for the shoulder and child shoulders (calls initiated by forwarding and/or parallel calls within the current routing process).
Specifically, it allows you to establish:

dialog_timeoutsec - Limit on the duration of a call (from 5 to 7200).
fork_timeoutsec - specific shoulder call time (from 3 to 180).
fork_fromuri - a representation of the caller.

The set value is applied to all child shoulders unless an individual setting from another group is applied to them in the continuation of the routing process.
Default value - does not apply the group parameter. Value "undefined" - resets the previously applied parameter.

Table 4. Parameters
Field: `filter_from` Mode: `in` Type: `str` Default: `*`	Source number filter mask. The result of the modification by the routing rules applied in the previous steps is checked. Initially the source number from the username field of the Referred-By header, and in its absence from the From header, SIP-request INVITE, or the result of a more complex definition of the initiator subscriber number (e.g. sipuser phonenumber, the result of applying sipuser extension, callerid to esg conversion rules, etc.) is checked. Filter operation modes.
`Field: filter_by Mode: in Type: str Default: *`	Mask-filter the number of the caller who forwarded the call. Filter operation modes.
`Field: numbers_to Mode: in Type: array<str> Default: []`	List of numbers that activate the group when a call is received.
`Field: dialog_timeoutsec Mode: in Type: int Default: 7200`	Maximum dialog duration, seconds. A value of `0` or an invalid value - does not change the parameter. The `"undefined"` value resets the value of previously applied type groups 'options'. The set value is limited to a range of 5 to 7200 seconds.
`Field: fork_timeoutsec Mode: in Type: int Default: 0`	Shoulder call timeout, seconds. Applies to all shoulders that are children of the current call within the current routing process. Forwarded and parallel calls are taken into account". A subsequent application of a group of the same type to other child recipients may change. A value of `0` or an invalid value - does not change the parameter. The `"undefined"` value resets the value of previously applied type groups 'options'. The set value is limited to an interval of 3 to 180 seconds.
`Field: fork_fromuri Mode: in Type: str Default: empty`	Caller Presentation. Applies to all shoulders that are children of the current call within the current routing process. Forwarded and parallel calls are taken into account". A subsequent application of a group of the same type to other child recipients may change. Only username and displayname. The `"undefined"` value resets the value of previously applied type groups 'options'. Empty string or incorrect URI format - does not change the parameter.

Example

{
  "filter_from": "*",
  "filter_by": "*",
  "numbers_to": ["205","206"],
  "fork_timeoutsec": 3,
  "fork_fromuri": "\"DISPLAY NAME\" <sip:username@domain>"
}

Parallel call group (parallel)

Call parallelization group depending on the mask of the call initiator and optionally the call transfer initiator.

Any call to the account number specified in the 'numbers_to' list results in a simultaneous call to the parallel numbers specified in the 'numbers_parallel' field.
Any is direct, group, translated, forwarded, from a script.
In case such a number is called as a parallel number from another functional group, the application of the parallel numbers set for it depends on the cascade property of the functional group.

Is a common alternative to setting up an individual parallel call in SIP user account.
In this case, the call in the statistics is bound to the real owner of the destination number.

Table 5. Parameters
Field: `filter_from` Mode: `in` Type: `str` Default: `*`	Source number filter mask. The result of the modification by the routing rules applied in the previous steps is checked. Initially the source number from the username field of the Referred-By header, and in its absence from the From header, SIP-request INVITE, or the result of a more complex definition of the initiator subscriber number (e.g. sipuser phonenumber, the result of applying sipuser extension, callerid to esg conversion rules, etc.) is checked. Filter operation modes.
`Field: filter_by Mode: in Type: str Default: *`	Mask-filter the number of the caller who forwarded the call. Filter operation modes.
`Field: numbers_to Mode: in Type: array<str> Default: []`	List of numbers that activate the group when a call is received.
`Field: numbers_parallel Mode: in Type: array<str> Default: []`	List of numbers used to initiate a parallel call. In either case, calls will be sent to each of the target numbers once.

Example

{
  "filter_from": "*",
  "filter_by": "*",
  "numbers_to": ["205","206"],
  "numbers_parallel": ["205","206","207"]
}

Chief-Secretary Group (chief)

When a call to the chief is received from numbers not on the direct access list, the secretaries are called.

The decision whether the initiator is allowed to make a direct call to the chief is made based on the filter applied to the number of the subscriber who transferred or forwarded the call to the chief.

At the same time, the group authorizes call interception, BLF subscriptions between the chief and secretaries, and places details on the incoming call in BLF notifications for display on the device panel so that the group subscribers can see the initiator of the call and can intercept.
Thus between the chief and the secretaries, there is no need to configure separate permissions rules featurerules for the following feature types:
* pickup, callwaiting, blf, blf_details - in all directions;
* intercom, barge - from the chief to the secretaries.

In order for the mode to work fully, it is necessary:
* enable the 'blf_details_enabled' option in the domain settings;
* set up BLF subscriptions on the chief’s and secretaries' phones as needed (so that the secretaries can see the chief’s status, the chief can see the secretaries' status);
* configure the chief and secretary phones to display information about the call initiator when a BLF message is received (Yealink: account.X.dialoginfo_callpickup=1, features.pickup.blf_visual_enable=1);
* restrict the use of BLF visualization on the chief and secretary phones to a specific list of numbers (Yealink: features.pickup.blf_visual.list=101,102,103 or any);
* if audio notification of a call to the chief’s number is required, set up the secretaries' phones to play a melody when receiving a BLF message (Yealink: features.pickup.blf_audio_enable=1), customize the melody, and specify restrictions on the use of BLF audio notification for a certain list of numbers (Yealink: features.pickup.blf_audio.list=101,102,103 or any).

With the above settings, the subscriber’s phone displays the incoming calls of the tracked subscriber on the display, providing an opportunity to intercept the selected one.
Interception is accomplished by sending an INVITE with the Replaces header (rather than calling subscriber function code, since it is not possible to specify a specific call to intercept in this mode).

There is an alternative setup with interception via subscriber function code:
* create subscriber function code with the type "intercept by number" and configure its availability in routing rules;
* set up interception support on the chief and secretaries' phones by setting the number of the corresponding ficacode (Yealink: account.x.direct_pickup_code);
* when setting up BLF subscriptions on the chief and secretaries' phones, specify an intercept number (the same subscriber function code) for each of them.

In order for the mode with interception via ficacode to work, you need to turn off the option on the phone (Yealink: account.X.dialoginfo_callpickup=0).
When using a 'intercept' type ficacode, it is not possible to specify a specific call to intercept if the monitored device receives multiple calls.
In this regard, in order to improve performance, it is advisable not to use granularity in BLF notifications by disabling the 'blf_details_enabled' option in the domain settings.

Table 6. Parameters
Field: `mode` Mode: `in` Type: `str` Default: `cascade`	Operating algorithm. Possible options: * `parallel` - when calling the chief’s number from any number not mentioned in the group, the call is forwarded to both assistants in parallel. * `cascade` - when calling the chief’s number from any number not mentioned in the group, the call is forwarded sequentially to the first assistant, then to the second assistant. * `direct` - when calling the chief’s number from any number, the call goes through without forwarding.
`Field: chief_number Mode: in Type: str Default: empty`	Chief Number.
`Field: assistant1_number Mode: in Type: str Default: empty`	First Assistant Number.
`Field: assistant2_number Mode: in Type: str Default: empty`	Second assistant number.
`Field: direct_numbers Mode: in Type: array<str> Default: []`	List of numbers directly going to the chief. Applies to the result of from/referred-by conversion by routing rules.
`Field: chief_mobile Mode: in Type: str Default: empty`	Chief’s mobile number. The number is used to automatically publish the status of the subscriber participating in the dialog. In this way, secretaries are able to make a BLF subscription to an external number and receive notifications when a dialog is completed. Permission to subscribe to the chief’s mobile number is automatically granted to secretaries. Case example: a secretary connects the chief on a mobile number sequentially to multiple callers. Extends the list of external numbers with state tracking, the list of which is set in domain settings.

Example

{
  "mode": "cascade",
  "chief_number": "101",
  "assistant1_number": "102",
  "assistant2_number": "103",
  "direct_numbers": ["115", "123"]
}

Random group (custom)

It is used to implement project logic.

Table 7. Parameters
Field: `filter_from` Mode: `in` Type: `str` Default: `*`	Source number filter mask. The result of the modification by the routing rules applied in the previous steps is checked. Initially the source number from the username field of the Referred-By header, and in its absence from the From header, SIP-request INVITE, or the result of a more complex definition of the initiator subscriber number (e.g. sipuser phonenumber, the result of applying sipuser extension, callerid to esg conversion rules, etc.) is checked. Filter operation modes.
`Field: filter_by Mode: in Type: str Default: *`	Mask-filter the number of the caller who forwarded the call. Filter operation modes.
`Field: numbers_to Mode: in Type: array<str> Default: []`	List of numbers that activate the group when a call is received.
`Field: type Mode: in Type: str Default: empty`	Project Group Type. Defines a set of other detail parameters.

Additionally

Filter operation modes

Mode Description

Mode	Description
`Posymbolic`	The value to be subjected to the conformance check is passed through the filter character by character. The following special characters and combinations may be used: `X` – any character; `*` – all remaining characters; `{F}` and `{f}` is the original From username in its entirety; `{T}` and `{t}` is the original value of To username in its entirety; `{E}` and `{e}' is an empty value. `?` - any character (if used for filtering by domain names, any character except dot - domain name separator). `$` - to filter by domain. Any sequence of characters other than a dot - domain name separator. If it is necessary to specify one of the service characters as a target character, it should be enclosed in square brackets, e.g. `[X]`. For example, `XXX` is any three-character value.
`Table`	The `{tab:…}` substring can be used. It can be used to select a group of characters in the tested value and match them with the table embedded in the rule (`opts.tab`). For example, `{tab:a}` - select a substring and map it to the `a` field of all objects/rows in the table. The table serves as a bundle of several filter fields and modifiers. Based on the sequential check of filters, there are fewer rows in the table, taking into account the detected matches. The first of the remaining rows is used for application in modifiers. If there are no rows left in the table, the rule is rejected. Capturing characters from the mask-based value being checked can be done automatically, or with strict specification of the substring length: `{tab:KEY}` - Automatic capture from the value being tested. `{tab:KEY:LENGTH}` - Capture the specified number of characters from the value being checked. Field values in the table can be used as field values: constants (for this value a specific value must be specified); regular expressions (to do this, you must specify a value in the format `/reg/EXPRESSION`, e.g. `/reg/^1[1-4]$`); mapping with other fields of the table (for this purpose it is necessary to specify the value in `/tab/FIELD` format, for example `/tab/a`). The mode is used to bind values of different fields. For example, to allow calls only to your own voice mailbox. The binding order must be strictly observed: if the referenced table field has not been checked yet and has not been filled with the real value of another entity field, the matching will fail. The order of checking entity fields: filter_from, filter_by; any value applied without a regular expression (for this purpose `/any` must be set). The mode is useful only when organizing direct comparisons with values of other fields without additional filters. The tabular modifier may be used in combination with other character mode control commands. Multiple specification of fields in one modifier, repetition, specification of non-existent fields are allowed. For example, `{tab:a:3}XXXXX{tab:b}` - allows you to highlight the 3-character city code in the number and map it to the `a` field in the table, and simultaneously highlight the tail starting at the 9th character and map it to the `b` field in the table.
`Regex`	The pattern is applied to the original value Pattern. The structure of a regex pattern value: `/reg/Pattern1`. For example,- significance: `"302"` - mask: `"/reg/0"` - Result: `true`. significance: `"302"` mask: `"/reg/^0$"` Result: `false`. significance: `"302"` mask: `"/reg/^302$"` Result: `true`. significance: `"302"` mask: `"/reg/^(301\|302\|305)$"` Result: `true`. All standard regular expression rules can be applied when forming Pattern patterns.
`Range`	The value subject to compliance checking is a numeric integer and is within the specified numeric range. The structure of the dia-template value: `/dia/FromValue+N` - fall under the pattern of N+1 values from FromValue to FromValue+N. For example,- significance: `"302"` - mask: `"/dia/300+10"` - Result: `true`.

Posymbolic

The value to be subjected to the conformance check is passed through the filter character by character.
The following special characters and combinations may be used:

X – any character;
* – all remaining characters;
{F} and {f} is the original From username in its entirety;
{T} and {t} is the original value of To username in its entirety;
{E} and `{e}' is an empty value.
? - any character (if used for filtering by domain names, any character except dot - domain name separator).
$ - to filter by domain. Any sequence of characters other than a dot - domain name separator.

If it is necessary to specify one of the service characters as a target character, it should be enclosed in square brackets, e.g. [X].

For example, XXX is any three-character value.

Table

The {tab:…} substring can be used. It can be used to select a group of characters in the tested value and match them with the table embedded in the rule (opts.tab).
For example, {tab:a} - select a substring and map it to the a field of all objects/rows in the table.
The table serves as a bundle of several filter fields and modifiers. Based on the sequential check of filters, there are fewer rows in the table, taking into account the detected matches.
The first of the remaining rows is used for application in modifiers. If there are no rows left in the table, the rule is rejected.
Capturing characters from the mask-based value being checked can be done automatically, or with strict specification of the substring length:

{tab:KEY} - Automatic capture from the value being tested.
{tab:KEY:LENGTH} - Capture the specified number of characters from the value being checked.

Field values in the table can be used as field values:

constants (for this value a specific value must be specified);
regular expressions (to do this, you must specify a value in the format /reg/EXPRESSION, e.g. /reg/^1[1-4]$);
mapping with other fields of the table (for this purpose it is necessary to specify the value in /tab/FIELD format, for example /tab/a). The mode is used to bind values of different fields. For example, to allow calls only to your own voice mailbox. The binding order must be strictly observed: if the referenced table field has not been checked yet and has not been filled with the real value of another entity field, the matching will fail. The order of checking entity fields: filter_from, filter_by;
any value applied without a regular expression (for this purpose /any must be set). The mode is useful only when organizing direct comparisons with values of other fields without additional filters.

The tabular modifier may be used in combination with other character mode control commands.
Multiple specification of fields in one modifier, repetition, specification of non-existent fields are allowed.

For example, {tab:a:3}XXXXX{tab:b} - allows you to highlight the 3-character city code in the number and map it to the a field in the table, and simultaneously highlight the tail starting at the 9th character and map it to the b field in the table.

Regex

The pattern is applied to the original value Pattern.

The structure of a regex pattern value:
/reg/Pattern1.

For example,- significance: "302"
- mask: "/reg/0"
- Result: true.

significance: "302"
mask: "/reg/^0$"
Result: false.
significance: "302"
mask: "/reg/^302$"
Result: true.
significance: "302"
mask: "/reg/^(301|302|305)$"
Result: true.

All standard regular expression rules can be applied when forming Pattern patterns.

Range

The value subject to compliance checking is a numeric integer and is within the specified numeric range.

The structure of the dia-template value:
/dia/FromValue+N - fall under the pattern of N+1 values from FromValue to FromValue+N.

For example,- significance: "302"
- mask: "/dia/300+10"
- Result: true.

Functional group (sipkit)

Description

Limitations

Fields

Types of groups

Forwarding group (redirect)

Failure Group (reject)

Call option setting group (options)

Parallel call group (parallel)

Chief-Secretary Group (chief)

Random group (custom)

Additionally

Filter operation modes

See also

API

Logical roles