Sippy Software, Inc.

The Sippy B2BUA can use external script to change a set of parameters of the call, e.g. set custom CLI, CLD for particular call scenario. 

There are two scripts that could be used for this purpose:

• /var/env<I_ENVIRONMENT>/scripts/external_translator - script that is applied during authorization of the call
• /var/env<I_ENVIRONMENT>/scripts/external_translator_outbound - script that is applied before sending the call to Vendor/Trunk. Available starting from 2021 version

external_translator script

The B2BUA sends to the standard input of the script the CLI, CLD and i_account, for example: 

Fields supplied by Sippy to external_translator script:

I_ACCOUNT - unique ID of an Account
ORIG_CLI - username part of From header, original number of Caller's party
ORIG_CLD - username part of To header, original number of Called party
CLI - number of Caller's party after applying account level translations
CLD - number of Called party after applying account level translations
CALLER_NAME - the Display Name of Caller
P_ASSERTED_ID - username part of P-Asserted-ID header
REMOTE_PARTY_ID - username part of Remote-Party-Id header
REMOTE_IP - IP address of Caller
DIVERSION - username part of Diversion header
DIVERSION_PARAMS - additional parameters for the Diversion header

After receiving the empty line, the script is free to use some algorithm to rewrite the CLI, CLD or other parameters and then it MUST send them in separate lines of text - CLI, CLD and empty line. For example:

If the script is not configured to rewrite anything then it must send back the CLI and CLD unchanged.

Returned parameters:

CLI - desired CLI
CLD - desired CLD
CALLER_NAME - desired Caller Name
FAIL=<yes|no> - you can use this field to signal that the call should fail. Example: FAIL=yes
RESULT=<integer> - the result to be responded to the calling party. Possible values are 400 through 699 excluding 401 and 407, default is 500. This field is used when the FAIL=yes. Example: RESULT=403
COST=<float> - this value will be added to overall cost of the call. Example: COST=0.01

** parameters available starting from SIppy2020
TO_URI_PARAMS - the parameters for the To: SIP URI (not address)
FROM_URI_PARAMS - the parameters for the From: SIP URI (not address)
RURI_PARAMS - additional request URI parameters for the outgoing INVITE
DIVERSION_URI_PARAMS - the parameters for the Diversion: SIP URI
DIVERSION_PARAMS - additional parameters for the Diversion header. Note that the parameter 'reason' will be present even if it has not been returned by the external translator.
P_ASSERTED_ID_PARAMS - the parameters for the P-Asserted-Identity: SIP address
P_ASSERTED_ID_URI_PARAMS - the parameters for the P-Asserted-Identity: SIP URI
REMOTE_PARTY_ID_PARAMS - the parameters for the Remote-Party-ID: SIP address
REMOTE_PARTY_ID_URI_PARAMS - the parameters for the Remote-Party-ID: SIP URI
ADD_HEADER - additional header to be generated by Sippy that should be added in outgoing INVITE sent to Vendor

WARNING! To achieve maximum performance the script should never exit but continue to process next portion of data.

The SSP distribution comes with sample scripts which you can customize to your purposes:

• /home/ssp/scripts/external_translator.sample 
• /home/ssp/scripts/external_translator.py (in >=Sippy2020)

A simple example of translator script:

#!/bin/sh

while true; do
  read LINE || exit
  case "$LINE" in
  CLI=*) CLI=${LINE#CLI=}
  ;;
  CLD=*) CLD=${LINE#CLD=}
  ;;
  ORIG_CLI=*) ORIG_CLI=${LINE#ORIG_CLI=}
  ;;
  ORIG_CLD=*) ORIG_CLD=${LINE#ORIG_CLD=}
  ;;
  "")
  echo "CLI=$CLI"
  echo "CLD=$CLD"
  echo
  CLI=""
  CLD=""
  ;;
  esac
done

external_translator is applied after authentication of the call. Translation rules are applied in the following order:

• Case call was authenticated to an Account:

1. CLI/CLD translation rules from Authentication Rule (if present)

2. CLI/CLD translation rules from Account (if present)

3. external_translator is triggered and processes the fields supplied to it by Sippy (see the list below)

4. Based on the output from external_translator Sippy performs call authorization (rating, routing, selection of tariff, route, etc)

5. Before sending the call outside the translation rules from Connection/Trunk are applied.

• Case call was authenticated to DID

1. CLI/CLD translation rules from DID Authentication Rule and DID (if present)

2. CLI/CLD translation rules from Account assigned to DID are ignored

3. external_translator is triggered and processes the fields supplied to it by Sippy (see the list below)

4. Based on the output from external_translator Sippy performs call authorization (rating, routing, selection of tariff, route, etc)

5. Before sending the call outside the translation rules from Connection/Trunk are applied.

external_translator_outbound script. Available starting from 2021 version

It is applied before sending the call to vendor and is invoked for each routing entry tried.

The B2BUA sends to the standard input of the script the CLI, CLD and i_account, for example: 

Fields supplied by Sippy to external_translator_outbound script:

I_ACCOUNT - unique ID of an Account
I_VENDOR - unique ID of a Vendor
I_CONNECTION - unique ID of a Connection
ORIG_CLI - username part of From header, original number of Caller's party
ORIG_CLD - username part of To header, original number of Called party
CLI1 - number of Caller party after applying account level translations
CLD1 - number of Called party after applying account level translations
CLI - number of Caller party after applying account and Connection level translations
CLD - number of Called party after applying account and Connection level translations
CALLER_NAME - the Display Name of a Caller

After receiving the empty line, the script is free to use some algorithm to rewrite the CLI, CLD or other parameters and then it MUST send them in separate lines of text - CLI, CLD and empty line. For example:

If the script is not configured to rewrite anything then it must send back the CLI and CLD unchanged.

Returned parameters:

CLI - desired CLI
CLD - desired CLD
CALLER_NAME - desired Caller Name
ADD_HEADER - additional header generated by Sippy, which will be added in outgoing call INVITE sent to Vendor

WARNING! To achieve maximum performance the script should never exit but continue to process next portion of data.

The SSP distribution comes with sample scripts which you can customize to your purposes:

• /home/ssp/scripts/external_translator_outbound.sample

A simple example of translator_outbound script:

#!/bin/sh

while true; do
    read LINE || exit
    case "$LINE" in
    I_ACCOUNT=*) I_ACCOUNT=${LINE#I_ACCOUNT=}
        ;;
    I_VENDOR=*) I_VENDOR=${LINE#I_VENDOR=}
        ;;
    I_CONNECTION=*) I_CONNECTION=${LINE#I_CONNECTION=}
        ;;
    ORIG_CLI=*) ORIG_CLI=${LINE#ORIG_CLI=}
        ;;
    ORIG_CLD=*) ORIG_CLD=${LINE#ORIG_CLD=}
        ;;
    CLI1=*) CLI1=${LINE#CLI1=}
        ;;
    CLD1=*) CLD1=${LINE#CLD1=}
        ;;
    CLI=*) CLI=${LINE#CLI=}
        ;;
    CLD=*) CLD=${LINE#CLD=}
        ;;
    CALLER_NAME=*) CALLER_NAME=${LINE#CALLER_NAME=}
        ;;
    "")
        if [ ${I_ACCOUNT} -eq '34' ]; then
          echo CLI=translator_outbound_cli_match_${CLI}
          echo CLD=${CLD}
          echo CALLER_NAME=Acc34_matched_${CALLER_NAME}
        else
          echo CLI=Unknown_account_${CLI}
          echo CLD=${CLD}_vendor_unknown
          echo CALLER_NAME=Unknown_account_${CALLER_NAME}
        fi
        echo
        CLI=""
        CLD=""
        CALLER_NAME=""
        ;;
    esac
done