You are here: Integration > External and local policy > Writing local policy scripts

Writing local policy scripts

Local policy allows you to manipulate service configuration and media location data (that has been provided either via the external policy API, or has been retrieved from Pexip Infinity's own database) by running a jinja2 script against that data.

Using local policy requires proficient scripting skills. For large production environments we recommend that you contact your Pexip authorized representative.

We recommend that you test your policy scripts carefully with a variety of different inputs. We will attempt to maintain backwards compatibility in future releases of the Pexip Infinity platform but the introduction of new features may affect the behavior of existing scripts. We strongly recommend that you test your scripts in a lab environment before using them in a production system, particularly after an upgrade to the Pexip Infinity software.

This topic covers:

Your scripts are configured as part of a policy profile (Call control > Policy profiles). The following table shows when the types of configuration data that can be modified via local policy are requested within Pexip Infinity:

Type of data Purpose
Service configuration

Obtains the configuration details of a service. Pexip Infinity typically makes this request when it:

  • receives an incoming call request
  • needs to place a call to a given alias
Media location

Obtains the system location to use for media allocation. A Conferencing Node assigned to that location will handle the media for the participant. A media location request is often made after a service configuration data request.

Writing a jinja2 script to control call behavior

Pexip Infinity's local policy scripts are based on a subset of the jinja2 templating language (http://jinja.pocoo.org/docs/dev/). Note that Pexip Infinity also uses jinja2 when Provisioning VMRs and devices from Active Directory via LDAP.

These scripts are made up of the following elements:

  • variables that are substituted with values from the source request (call_info), or that contain the existing configuration data supplied by external policy or the Pexip Infinity database (service_config and suggested_media_overflow_locations)
  • filters that can manipulate text or modify the content of variables or text strings, such as pex_update or pex_to_json
  • delimiters such as {{...}} and pipes | which are used to define filter expressions
  • jinja statements and control structures (see http://jinja.pocoo.org/docs/dev/templates/#list-of-control-structures)

A basic example media location script could be:

{
  {% if call_info.location == "Oslo" %}
    "result" : {
      "location" : "Oslo",
      "primary_overflow_location" : "London",
      "secondary_overflow_location" : "New York"
    } 
  {% else %}
    "result" : {
      "location" : "New York",
      "primary_overflow_location" : "London",
      "secondary_overflow_location" : "Oslo"
    } 
  {% endif %}
}

This script tests if the system location handling the incoming call request is "Oslo" and if so sets the location to be used for media to "Oslo", and sets "London" and "New York" as the primary and secondary overflow locations to be used if "Oslo" is out of capacity. For all other system locations handling incoming calls, the location to be used for media will be "New York", with "London" and "Oslo" as the primary and secondary overflow locations.

The following sections provide full information about how to construct a script, use filters, and update/refer to variables.

Getting started in constructing a script

Local policy allows you to manipulate the service configuration and media location data that has already been fetched from Pexip Infinity's own database or has been supplied via the external policy API. And in the case of service configuration data, there may be no data available — for example if a call attempt was made to an alias that does not exist.

This existing configuration data is held in two variables: service_config (for service configuration policy) and suggested_media_overflow_locations (for media location policy).

Your local policy script will typically use filters to modify some elements of these two variables, or replace the contents of those variables with completely different data, based on certain conditions, or it can choose to pass through the existing data unchanged. Those conditions will typically involve references to that existing data or to the original call information that led to the request to provide service configuration and media location data. That existing call information is held in the call_info variable and is explained in Supported variables below.

The objective of the script is to return the service configuration or media location data to Pexip Infinity. That response to Pexip Infinity i.e. the output/result of the script, must be a JSON object. (Note that the returned data takes the same format as the responses to external policy API requests.)

This is an example response containing service configuration data:

{
"action" : "continue",
"result" : {
  "service_type" : "conference",
  "name" : "Alice Jones",
  "service_tag" : "abcd1234",
  "pin" : "1357",
  }
}

See Service configuration data responses for full details.

This is an example response containing media location data:

{
"result" : {
  "location" : "London",
  "primary_overflow_location" : "Oslo"
  }
}

See Media location data responses for full details.

To help you construct and test your scripts, Pexip Infinity has a built-in script testing facility. Also, the example scripts included at the end of this topic illustrate how to structure your scripts.

Supported filters

Pexip Infinity supports a subset of filters from the jinja2 templating language and some custom Pexip filters. These filters are typically used to manipulate data. The most useful filters that you will need when writing local policy scripts are described below.

pex_update

The pex_update filter is used to update the service_config (service configuration data) and suggested_media_overflow_locations (media location data) variables.

Example usage: {{service_config|pex_update({"pin":"1234", "guest_pin":"", "allow_guests" : false}) }}

This updates 3 of the data elements in the service_config variable. It sets the pin to 1234, the guest_pin to null and the allow_guests flag to false. (See Service configuration data responses for a list of all of the elements in the service_config variable, and Media location data responses for a list of all of the elements in the suggested_media_overflow_locations variable.)

pex_to_json

The pex_to_json filter is used to convert the data in the service_config and suggested_media_overflow_locations variables into JSON format (which is the required data structure for the configuration data returned to Pexip Infinity).

Example usage: {{suggested_media_overflow_locations|pex_to_json}}

The example above converts the suggested_media_overflow_locations variable into JSON format.

Example usage: {{service_config|pex_update({"participant_​limit":10, "ivr_theme_name":"funky"})|pex_to_json}}

This second example combines the pex_update filter with the pex_to_json filter. It makes updates to the service_config variable and then converts it to JSON.

pex_debug_log

The pex_debug_log filter can be used to help debug your script. It writes debug messages to the Pexip Infinity support log. You can include literal text and variables.

Example usage: {{pex_debug_log("Media location policy ", call_info.location, " protocol", call_info.protocol) }}

This will generate a support log entry in the style of: Name="support.jinja2" pex_debug_log Detail="Media location policy ,Oslo, protocol,sip"

To avoid filling the support log and causing it to rotate, remove all pex_debug_log filters from your scripts as soon as they are working correctly.

To see the full range of available jinja2 filters, see the Supported filters section in the Provisioning VMRs and devices from Active Directory via LDAP topic.

Supported variables

There is a limited set of system variables (Configuration variables and Call information variables) that you can use within your script. Capitalization of variable names is important. The variables must be spelled exactly as shown.

Configuration variables

The service configuration and media location data that has already been fetched from Pexip Infinity's own database or has been supplied via the external policy API is held in the following variables:

  • service_config: this holds the existing service configuration data. This variable only applies to scripts run as service configuration policy.
    • When referring to specific service configuration data elements, you must use the service_config prefix. For example, use service_config.pin to refer to the service PIN, and service_config.service_type to refer to the type of service ("conference", "lecture" etc). See Service configuration data responses for the full set of service configuration elements within the service_config variable.
    • If no service configuration data has been retrieved — for example if a call attempt was made to an alias that does not exist, this variable will be null, but it can still be updated to contain the required configuration data.

    Example service_config data (in JSON format):

    "service_config": {
  "allow_guests": true, 
  "automatic_participants": [
  {
    "description": "Dial out to VMR owner", 
    "local_alias": "meet.alice@example.com", 
    "local_display_name": "Alice's VMR", 
    "protocol": "sip", 
    "remote_alias": "sip:alice@example.com", 
    "role": "chair", 
    "system_location_name": "London"
  }
  ], 
  "description": "Alice Jones personal VMR", 
  "enable_overlay_text": true, 
  "guest_pin": "5678", 
  "name": "Alice Jones", 
  "pin": "1234", 
  "service_tag": "abcd1234", 
  "service_type": "conference"
}

  • suggested_media_overflow_locations: this holds the existing media location data. This variable only applies to scripts run as media location policy. When referring to specific media location data elements, you must use the suggested_media_overflow_locations prefix followed by the element name — either location, primary_overflow_location or secondary_overflow_location which respectively refer to the principal location and the primary and secondary overflow locations that will handle the call media, for example suggested_media_overflow_locations.location.

    Example suggested_media_overflow_locations data (in JSON format):

    "suggested_media_overflow_locations": {
  "location": "New York", 
  "primary_overflow_location": "Paris", 
  "secondary_overflow_location": "Peckham"
}

Call information variables

The following table shows the call information variables that may be available to your script. For each variable the table indicates if it is available to service configuration data requests and/or media location data requests. When using these variables you must use the "call_info." prefix. For example to refer to the location associated with the Conferencing Node making the request, use call_info.location and to refer to the call protocol use call_info.protocol. (Note that the call_info variables are the same as those used in external policy API requests.)

Available call_info variables Description Service config Media location
bandwidth The maximum requested bandwidth for the call.

call_direction

The direction of the call that triggered the request.

Values: "dial_in" (calls in to Pexip Infinity), "dial_out" (calls dialed out from Pexip Infinity), or "None" (other policy triggers, for example if a SIP Subscribe request is received).

local_alias

In the context of service configuration requests, this is the incoming alias (typically the alias that the endpoint has dialed). This is the primary item of information that the policy server will use to return appropriate service configuration data.

For participant requests (media location and participant avatar) this contains the originally-dialed incoming alias for the associated service.

location The name of the Pexip Infinity system location associated with the Conferencing Node making the request/notification.

ms_subnet †

The sender's subnet address.

Note that the value of "ms_subnet" is formatted as a JSON list, for example: ["10.47.5.0"]

node_ip The IP address of the Conferencing Node making the request.

p_asserted_identity†

The authenticated identity of the user sending the SIP message.

Note that the value of "p_asserted_identity" is formatted as a JSON list, for example: ['"Alice"<sip:alice@example.com>']

protocol

The call protocol.

Values: "api", "webrtc", "sip", "rtmp", "h323" or "mssip".

(Note that the protocol is always reported as "api" when an Infinity Connect client dials in to Pexip Infinity.)

pseudo_version_id The Pexip Infinity software build number.

remote_address The IP address of the remote participant.

remote_alias The name of the user or the registered alias of the endpoint. The remote_alias may include scheme information, for example sip:alice@example.com.

remote_display_name The display name of the remote participant.

remote_port The IP port of the remote participant.

registered

Whether the remote participant is registered or not.

Values: "True" or "False".

service_name The service name. This will match the name field returned by the policy server from the original service configuration request.  

service_tag The service tag associated with the service_name parameter.  

unique_service_name

The unique name used by Pexip Infinity to identify the service:

  • For "gateway" services this is the matching rule name followed by a unique identifier (so as to distinguish between separate calls that match the same rule).
  • For all other services, this is the same as the service_name parameter.
  

vendor System details about the remote participant, such as manufacturer name and version number for hard endpoints, or browser and operating system details for soft clients.

version_id The Pexip Infinity software version number.

† only included if the request was triggered by a SIP message, and the parameter is included as a field in the SIP message header; in addition the ms_subnet and p_asserted_identity fields use only underscores and lower case characters in their names when used in local policy (normally they are referenced as ms-subnet and p_Asserted-Identity)

For example, the call_info variable could contain the following data (in JSON format):

"call_info": {
  "bandwidth": 0, 
  "call_direction": "dial_in", 
  "local_alias": "meet.alice.vmr@example.com", 
  "location": "New York", 
  "node_ip": "10.55.55.101", 
  "protocol": "api", 
  "pseudo_version_id": "33118", 
  "remote_address": "10.55.55.250", 
  "remote_alias": "bob@example.com", 
  "remote_display_name": "Bob T. User", 
  "remote_port": 64703, 
  "vendor": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.100 Safari/537.36", 
  "version_id": "14"
}

Response formats

The response to Pexip Infinity i.e. the output/result of the script, must be a JSON object.

The following sections explain how that response must be structured for service configuration data and for media location data. Note that the fields in a JSON object can be supplied in any order, and that the returned data takes the same format as the responses to external policy API requests.

ClosedService configuration data responses

The response to a service configuration request takes the basic format:

{
"action" : "reject|continue",
"result" : { <service_configuration_data> }
}

where:

  • "action" instructs Pexip Infinity how to proceed

    • "reject" instructs Pexip Infinity to reject the call immediately (i.e. return "conference not found")
    • "continue" use the data supplied in the "result" field
  • "result" is a JSON object of multiple key value pairs that describes the service. Some data fields are required, and some are optional. The fields expected by Pexip Infinity in the response depend upon the returned service_type — either "conference" or "lecture" for a Virtual Meeting Room or Virtual Auditorium, "gateway" for a Pexip Distributed Gateway call, "two_stage_dialing" for a Virtual Reception, or "test_call" for a Test Call Service.

The fields expected in the response for each service type are described below:

ClosedVirtual Meeting Room / Virtual Auditorium service types response fields

Pexip Infinity expects the following fields to be returned for a service_type of "conference" (VMR) or "lecture" (Virtual Auditorium):

Field name Required Type Description
service_type Yes String

The type of service, in this case:

  • "conference" — a Virtual Meeting Room, or
  • "lecture" — a Virtual Auditorium
name Yes String

The name of the service. The policy server typically determines the service name according to the local_alias received in the configuration request.

Pexip Infinity will subsequently use this name — as the service_name parameter — in subsequent requests.
description No String

A description of the service.
service_tag Yes String

A unique identifier used to track usage of this service.
pin No String

Host PIN — the secure access code for Host participants.
allow_guests No Boolean

Whether to distinguish between Host and Guest participants:

  • true — the conference has two types of participants: Hosts and Guests. The pin to be used by Hosts must be specified. A guest_pin can optionally be specified; if a guest_pin is not specified, Guests can join without a PIN.
  • false — all participants have Host privileges

Default: false
guest_pin No String

Guest PIN — the secure access code for Guest participants.
max_callrate_in No Integer

The maximum media bandwidth in bps that Pexip Infinity will receive from each individual participant dialed in to the service. Range 128000 to 4096000 bps.
max_callrate_out No Integer

The maximum media bandwidth in bps that Pexip Infinity will send to each individual participant dialed in to the service. Range 128000 to 4096000 bps.
participant_​limit No Integer

The maximum number of participants allowed to join the service.
ivr_theme_name No String

The name of the theme to use with the service. If no theme is specified, the default Pexip theme is used.
automatic_​participants No List

A list of participants to dial automatically when the conference starts. Each participant in the list contains a number of fields as described in Automatically dialed participants (ADP) fields.

view

(applies to service_type of "conference" only)

 No String

The layout seen by all participants:

  • "one_main_zero_pips" — full-screen main speaker only
  • "one_main_seven_pips" — large main speaker and up to 7 other participants
  • "one_main_twentyone_pips" — main speaker and up to 21 other participants
  • "two_mains_twentyone_pips" — two main speakers and up to 21 other participants

Default: "one_main_seven_pips"

host_view

(applies to service_type of "lecture" only)

 No String

The layout seen by Hosts:

  • "one_main_zero_pips" — full-screen main speaker only
  • "one_main_seven_pips" — large main speaker and up to 7 other participants
  • "one_main_twentyone_pips" — main speaker and up to 21 other participants
  • "two_mains_twentyone_pips" — two main speakers and up to 21 other participants

Default: "one_main_seven_pips"

guest_view

(applies to service_type of "lecture" only)

 No String

The layout seen by Guests:

  • "one_main_zero_pips" — full-screen main speaker only
  • "one_main_seven_pips" — large main speaker and up to 7 other participants
  • "one_main_twentyone_pips" — main speaker and up to 21 other participants
  • "two_mains_twentyone_pips" — two main speakers and up to 21 other participants

Default: "one_main_seven_pips"

Only Hosts are displayed. Guests can hear but not see any of the other Guests.
enable_overlay_text No Boolean

If enabled, the display name or alias of each main speaker is shown. For more information, see Showing the names of speakers.

  • true — speaker names are shown
  • false — speaker names are not shown

Default: false
locked No Boolean

Whether to lock the conference on creation:

  • true — the conference will be locked on creation
  • false — the conference will not be locked

Note that this field has no effect on the conference if it is already running.

Default: false
call_type No String

The call capability of the conference. It can be limited to:

  • "video" — main video plus presentation
  • "video-only" — main video only
  • "audio" — audio-only

Default: "video"

force_​​presenter_​into_main

(applies to service_type of "lecture" only)

 No Boolean

Controls whether the Host who is presenting is locked into the main video position:

  • true — the Host sending the presentation stream will always hold the main video position
  • false — the main video position is voice-switched

Default: false

mute_all_guests

(applies to service_type of "lecture" only)

 No Boolean

Controls whether to mute guests when they first join the conference:

  • true — mute guests when they first join the conference
  • false — do not mute guests when they first join the conference

Default: false
ClosedPexip Distributed Gateway service type response fields

Pexip Infinity expects the following fields to be returned for a service_type of "gateway":

Field name Required Type Description
service_type Yes String

The type of service, in this case:

  • "gateway" — a Pexip Distributed Gateway call
name Yes String

The name of the service. Ensure that all gateway service instances have a unique name to avoid conflicts between calls.

Pexip Infinity will subsequently use this name — as the service_name parameter — in subsequent requests.
description No String

A description of the service.
service_tag Yes String

A unique identifier used to track usage of this service.
max_callrate_in No Integer

The maximum media bandwidth in bps that Pexip Infinity will receive from each individual participant dialed in to the service. Range 128000 to 4096000 bps.
max_callrate_out No Integer

The maximum media bandwidth in bps that Pexip Infinity will send to each individual participant dialed in to the service. Range 128000 to 4096000 bps.
ivr_theme_name No String

The name of the theme to use with the service. If no theme is specified, the default Pexip theme is used.
remote_alias Yes String

The alias of the endpoint to call.

The alias can include scheme information, for example sip:alice@example.com, but the call will always be made using the specified outgoing_protocol.
local_alias Yes String The calling or "from" alias. This is the alias that the recipient would use to return the call.
local_display_name No String The display name of the calling alias.
outgoing_protocol Yes String

The protocol to use to place the outgoing call:

  • "h323" — an H.323 call; you can also optionally nominate an h323_gatekeeper_name
  • "sip" — a SIP call; you can also optionally nominate a sip_proxy_name
  • "mssip" — a Microsoft Lync / Skype for Business call; you can also optionally nominate an mssip_proxy_name and a turn_server_name
  • "rtmp" — uses the RTMP protocol; typically this is used for content streaming
outgoing_location_name No String The name* of the location of a Conferencing Node from which to place the call.
h323_gatekeeper_​name No String The name* of the H.323 gatekeeper to use to place the outgoing call. DNS is used if no gatekeeper is specified.
sip_proxy_name No String The name* of the SIP proxy to use to place the outgoing call. DNS is used if no proxy is specified.
mssip_proxy_name No String

The name of the Lync / Skype for Business server to use to place the outgoing call. DNS is used if no server is specified.
turn_server_name No String The name* of the TURN server to offer to external SIP and WebRTC endpoints that are ICE-enabled (such as Lync / Skype for Business clients and Infinity Connect WebRTC clients).
stun_server_name No String The name* of the STUN server to use when placing calls to external SIP and WebRTC endpoints that are ICE-enabled (such as Lync / Skype for Business clients and Infinity Connect WebRTC clients).
call_type No String

The call capability of the outbound call:

  • "video" — main video plus presentation
  • "video-only" — main video only
  • "audio" — audio-only
  • "auto" — match the capability of the outbound call to that of the inbound call

Default: "video"
called_device_type No String

The device or system to which to route the call:

  • "external" — route the call to a matching registered device if it is currently registered, otherwise attempt to route the call via an external system
  • "registration" — route the call to a matching registered device only (providing it is currently registered)
  • "mssip_conference_id" — route the call via a Lync / Skype for Business server to a Lync / Skype for Business meeting where the remote_alias is a Lync / Skype for Business Conference ID
  • "mssip_server" — route the call via a Lync / Skype for Business server to a Lync / Skype for Business client or meeting

Default: "external"
* The returned "name" must match the name of the location, H.323 gatekeeper, SIP proxy etc. configured within Pexip Infinity.
ClosedVirtual Reception service type response fields

Pexip Infinity expects the following fields to be returned for a service_type of "two_stage_dialing" (Virtual Reception):

Field name Required Type Description
service_type Yes String

The type of service, in this case:

  • "two_stage_dialing" — a Virtual Reception
name Yes String

The name of the service. The policy server typically determines the service name according to the local_alias received in the configuration request.

Pexip Infinity will subsequently use this name — as the service_name parameter — in subsequent requests.
description No String

A description of the service.
service_tag Yes String

A unique identifier used to track usage of this service.
max_callrate_in No Integer

The maximum media bandwidth in bps that Pexip Infinity will receive from each individual participant dialed in to the service. Range 128000 to 4096000 bps.
max_callrate_out No Integer

The maximum media bandwidth in bps that Pexip Infinity will send to each individual participant dialed in to the service. Range 128000 to 4096000 bps.
ivr_theme_name No String

The name of the theme to use with the service. If no theme is specified, the default Pexip theme is used.
call_type No String

The call capability of the reception. It can be limited to:

  • "video" — main video plus presentation
  • "video-only" — main video only
  • "audio" — audio-only

Default: "video"
mssip_proxy_name No String

The name of the Lync / Skype for Business server to use to place the outgoing call. DNS is used if no server is specified.
system_location_​name No String

This is an optional field used in conjunction with the mssip_proxy_name setting. If specified, a Conferencing Node in this system location will perform the Lync / Skype for Business Conference ID lookup on the Lync / Skype for Business server. If a location is not specified, the IVR ingress node will perform the lookup.
match_string No String

An optional regular expression used to match against the alias entered by the caller into the Virtual Reception. If the entered alias does not match the expression, the Virtual Reception will not route the call.

If this field is left blank, any entered alias is permitted. For more information, see Restricting or transforming the aliases entered into a Virtual Reception.
replace_string No String

An optional regular expression used to transform the alias entered by the caller into the Virtual Reception. (Only applies if a regex match string is also configured and the entered alias matches that regex.)

Leave this field blank if you do not want to change the alias entered by the caller.
ClosedTest Call Service type response fields

Pexip Infinity expects the following fields to be returned for a service_type of "test_call" (Test Call Service):

Field name Required Type Description
service_type Yes String

The type of service, in this case:

  • "test_call" — a Test Call Service
name Yes String

The name of the service. The policy server typically determines the service name according to the local_alias received in the configuration request.

Pexip Infinity will subsequently use this name — as the service_name parameter — in subsequent requests.
description No String

A description of the service.
service_tag Yes String

A unique identifier used to track usage of this service.
max_callrate_in No Integer

The maximum media bandwidth in bps that Pexip Infinity will receive from each individual participant dialed in to the service. Range 128000 to 4096000 bps.
ivr_theme_name No String

The name of the theme to use with the service. If no theme is specified, the default Pexip theme is used.
call_type No String

The call capability of the service. It can be limited to:

  • "video" — main video plus presentation
  • "video-only" — main video only
  • "audio" — audio-only

Default: "video"
ClosedAutomatically dialed participants (ADP) fields

The automatic_participants list field, which may be included in the service configuration response for a service_type of "conference" (VMR) or "lecture" (Virtual Auditorium), contains the following fields per participant:

Field name Required Type Description
remote_alias Yes String The alias of the endpoint to call.
remote_display_name No String

An optional friendly name for this participant. This may be used instead of the participant's alias in participant lists and as a text overlay in some layout configurations.
local_alias Yes String

The calling or "from" alias. This is the alias that the recipient would use to return the call.
local_display_​name No String The display name of the calling or "from" alias.
description No String

An optional description of the Automatically Dialed Participant.

Note that the description is for information purposes only. It has no subsequent effect in call processing.
routing No String

Specifies how to route the call:

  • "manual" — uses the requested protocol and the defaults for the specified system_location_name.
  • "routing_rule" — routes the call according to the configured Call Routing Rules— this means that the dialed alias must match an outgoing Call Routing Rule for the call to be placed (using the protocols and call control systems etc. as configured for that rule).

Default: "manual"
protocol Yes String

The protocol to use to place the outgoing call:

  • "h323" — an H.323 call
  • "sip" — a SIP call
  • "mssip" — a Microsoft Lync / Skype for Business call
  • "rtmp" — uses the RTMP protocol; typically this is used for content streaming

Calls are routed to externally-located participants based on the configuration of the system location used to place the call.
role Yes String

The level of privileges the participant has in the conference:

  • "chair" — the participant has Host privileges
  • "guest" — the participant has Guest privileges
dtmf_sequence No String

An optional DTMF sequence to be transmitted after the call to the dialed participant starts.
system_location_name No String The location of the Conferencing Node from which to place the call.
streaming No Boolean

Identifies the dialed participant as a streaming or recording device.

  • true — the participant is a streaming or recording device
  • false — the participant is not a streaming or recording device

Default: false
keep_conference_alive No String

Determines whether the conference continues when all other non-ADP participants have disconnected:

  • "keep_conference_alive" — the conference continues to run until this participant disconnects (applies to Hosts only).
  • "keep_conference_alive_if_multiple" — the conference continues to run as long as there are two or more "keep_conference_alive_if_multiple" participants and at least one of them is a Host.
  • "keep_conference_alive_never" — the conference terminates automatically if this is the only remaining participant.

Default: "keep_conference_alive_if_multiple"

For more information, see Automatically ending a conference.
call_type No String

The call capability of the participant. It can be limited to:

  • "video" — main video plus presentation
  • "video-only" — main video only
  • "audio" — audio-only

Default: "video"
presentation_url No String

This additional parameter can be specified for RTMP calls to send the presentation stream to a separate RTMP destination.

Example service configuration data responses

Response containing service configuration data

This is an example response of service configuration data for a "conference" service type:

{
"action" : "continue",
"result" : {
  "service_type" : "conference",
  "name" : "Alice Jones",
  "service_tag" : "abcd1234",
  "description" : "Alice Jones personal VMR",
  "pin" : "1234",
  "allow_guests" : true,
  "guest_pin" : "5678",
  "view" : "one_main_zero_pips",
  "enable_overlay_text" : true,
  "automatic_participants" : 
  [
    {
      "remote_alias" : "sip:alice@example.com",
      "remote_display_name" : "Alice",
      "local_alias" : "meet.alice@example.com",
      "local_display_name" : "Alice's VMR",
      "protocol" : "sip",
      "role" : "chair",
      "system_location_name" : "London"
    },
    {
      "remote_alias" : "rtmp://example.com/live/alice_vmr",
      "local_alias" : "meet.alice@example.com",
      "local_display_name" : "Alice's VMR",
      "protocol" : "rtmp",
      "role" : "guest",
      "streaming" : true
    }
  ]
  }
}

Response instructing Pexip Infinity to reject the call

This is an example response that tells Pexip Infinity to reject a call.

{
"action" : "reject"
}
ClosedMedia location data responses

The response to a media location request takes the format:

{
"result" : { <location_data> }
}

where "result" is a JSON object of key value pairs that describes the media location to use. The fields that may be included are:

Field name Required Description
location Yes The name* of the principal location to use for media allocation. A Conferencing Node assigned to that location will handle the media for the participant.
primary_overflow_location No The name* of the system location to handle the media if the principal location has reached its capacity.
secondary_overflow_location No The name* of the system location to handle the media if both the principal location and the primary overflow location have reached their capacity.
* The returned "name" must match the name of a location configured within Pexip Infinity. If any of the location names included in the response do not match a configured location within Pexip Infinity, the entire response is deemed to have failed and Pexip Infinity will fall back to its own default behavior for that request.

Example media location data response

This is an example response containing media location data:

{
"result" : {
  "location" : "London",
  "primary_overflow_location" : "Oslo"
  }
}

Testing your scripts

To help you construct and test your scripts, Pexip Infinity has a built-in script testing facility. It allows you to provide some test configuration data, run your script against that test data and check the output produced by your script.

To test your scripts:

  1. Go to Call control > Policy profiles and select the policy profile containing the script you want to test.

    (Note that you must select an existing profile.)

  2. Select Test local service configuration policy or Test local media location policy as appropriate (at the bottom of the page).
  3. You are taken to a script testing page where you can provide test input data and edit your script:

    • The Input field contains some example call_info and either some service_config data (for service configuration scripts) or some suggested_media_overflow_locations data (for media location scripts), in JSON format, that you can use as input data to test your script. You can use this data as is, or change the data to suit your needs, by adding or removing data elements. Ensure that you use valid call_info and service_config / suggested_media_overflow_locations data elements and maintain the correct JSON formatting.

      Note that you cannot include service_config data as input to a media location script, and you cannot use suggested_media_overflow_locations data as input to a service configuration script.

    • The Script field is initially populated with your current script from your policy profile. You can edit the script as required.
    • The Result field shows the result of running the input data against your script. If there is an error when running the script this field will contain a "reject" action.
    • The Diagnostics field contains any additional information (if available) pertaining to errors arising from running the test script against the test input.
  4. To test your script, edit the Input and Script fields as required and then select Test local service configuration policy / Test local media location policy (at the bottom of the page).
  5. Check the Result and Diagnostic fields to see the effect of your script.
  6. You can continue to edit the Input and Script fields and test your script until you are happy that the script is performing as expected.
  7. When you have finished testing your script:
    • Select Save changes and return to save the current contents of your script to your policy profile.
    • Select Cancel to return to your policy profile without saving the changes to your script.

Checking call information (call_info)

The contents of the call_info variable can vary within your Pexip Infinity system depending on the types of devices and call protocols in use. A good way to identify what information is actually being presented to your script is to include a pex_debug_log filter such as:
{{pex_debug_log("Call information ", call_info) }}

You can then make some test calls and look in the support log to see the actual call information that is being passed through to your script. To see the call information data go to Status > Support log and then search for entries that contain pex_debug_log. See Basic pass-through service configuration script with call_info debug line for a full example script.

Example scripts

Here is a set of example local policy scripts that illustrate how to structure a script, manipulate variables and format the data responses. You can use and adapt these scripts as appropriate for your own environment.

ClosedMinimum basic pass-through service configuration script

This is the smallest "no changes" service configuration script that you can use. It will allow a call to continue if it was going to be allowed anyway — and reject it if it was going to be rejected.

We recommend that you use this as the basis for your own scripts and add extra logic to get your desired functionality.

{
  {% if service_config %}
    "action" : "continue",
    "result" : {{service_config|pex_to_json}}
  {% else %}
     "action" : "reject",
     "result" : {}
  {% endif %}
}
ClosedBasic pass-through service configuration script with call_info debug line

This script extends the minimum "no impact" service configuration script above by adding a {{pex_debug_log("Call information ", call_info) }} line.

When this script runs it will not change any configuration data but it will record the contents of the call_info variable — all of the information relating to the call being processed — to the support log. This allows you to analyze the nature of the call information for different call types and help you construct your script appropriately. To see the call information data go to Status > Support log and then search for entries that contain pex_debug_log.

To avoid filling the support log and causing it to rotate, remove all pex_debug_log filters from your scripts as soon as they are working correctly.

{
  {{pex_debug_log("Call information ", call_info) }}
  {% if service_config %}
    "action" : "continue",
    "result" : {{service_config|pex_to_json}}
  {% else %}
     "action" : "reject",
     "result" : {}
  {% endif %}
}
ClosedMinimum basic pass-through media location script

This is the smallest "no changes" media location script that you can use. It simply returns the original set of suggested_media_overflow_locations without modification.

{
  "result" : {{suggested_media_overflow_locations|pex_to_json}}
}
ClosedUnconditionally nominate media locations

This media location script sets the location to be used for media to "Oslo", and sets "London" and "New York" as the primary and secondary overflow locations if "Oslo" is out of capacity. These locations will be used for every call / media location request, regardless of where call signaling is received.

{
  "result" : {
    "location" : "Oslo",
    "primary_overflow_location" : "London",
    "secondary_overflow_location" : "New York"
  } 
}
ClosedNominate a media location for RTMP streaming

This media location script explicitly sets the location to use for media to "DMZ" if the call being made is an outbound RTMP call (and also overrides any original primary and secondary overflow locations). All other call types will continue to use the original media locations.

{
  {% if 
    call_info.protocol == "rtmp" and
    call_info.call_direction == "dial_out"
  %}
    "result" : {
      "location" : "DMZ",
      "primary_overflow_location" : "Location B",
      "secondary_overflow_location" : "Location C"
    } 
  {% else %}
       "result" : {{suggested_media_overflow_locations|pex_to_json}}
  {% endif %}
}
ClosedRemove PIN based on location

This service configuration script removes the PIN for participants in "Location A" or "Location C" (these might, for example, be "internal" locations) but keeps any existing PIN requirements for participants in other locations.

{
  {% if service_config %}
    "action" : "continue",
    {% if call_info.location == "Location A" or call_info.location == "Location C" %}
      "result" : {{service_config|pex_update({"pin":"", "guest_pin":"", "allow_guests" : False})|pex_to_json}}
    {% else %}
      "result" : {{service_config|pex_to_json}}
    {% endif %}
  {% else %}
    "action" : "reject",
    "result" : {}
  {% endif %}
}
ClosedRemove PIN if device is registered

This service configuration script removes the PIN for participants if their device is registered to a Conferencing Node, but keeps any existing PIN requirements for participants in other locations.

{
  {% if service_config %}
    "action" : "continue",
    {% if call_info.registered %}
      "result" : {{service_config|pex_update({"pin":"", "guest_pin":"", "allow_guests" : False})|pex_to_json}}
    {% else %}
      "result" : {{service_config|pex_to_json}}
    {% endif %}
  {% else %}
    "action" : "reject",
    "result" : {}
  {% endif %}
}
ClosedInject an ADP into every conference (with a debug line for service_config)

This service configuration script adds an Automatically Dialed Participant (ADP) into every conference. Note that this script will override any existing ADPs that may be present in the service_config variable.

This example script also demonstrates how to use the pex_debug_log filter. It writes the original contents of the service_config variable to the support log.

To avoid filling the support log and causing it to rotate, remove all pex_debug_log filters from your scripts as soon as they are working correctly.

{
  {% if service_config %}
    {{pex_debug_log("service_config=", service_config) }}
    "action" : "continue",
    "result" : {{service_config|pex_update({"automatic_participants" :  [{"remote_alias":"participant@domain.com","local_alias":"policyuser@domain.com","local_display_name":"Local policy ADP","description":"Dial out to an ADP","protocol":"sip","role":"chair","system_location_name":"Location A" }]})|pex_to_json}}
  {% else %}
    "action" : "reject",
    "result" : {}
  {% endif %}
}

© 2017 Pexip AS