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).

encryption

The requested encryption mode.

Values: "On", "Off" or "Unknown" (encryption has not yet been determined).

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.

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.