In this section:

Related articles:

Overview

SIP Adaptor Profile

The SIP Adaptor Profile object is the main construct for SIP Message Manipulation (SMM) functionality. Using SMM criteria and actions, you define SMM rules within a SIP Adaptor Profile. The SBC applies the profile to SIP messages in order to modify their headers and/or parameters. When a message comes into or out of the SBC and a SIP Adaptor Profile applies, the message is evaluated based on the set of criteria in the profile. If the message meets the criteria, it is modified according to actions defined in the profile. You can assign SMM profiles at the global, address context, zone, and SIP trunk group levels. You have the option to define profiles at any or all of these levels. Refer to SIP Message Manipulation for more information on SMM.

For SIP Adaptor Profile provisioning limits, refer to SBC Provisioning Limits.


Note

The number of rules in a profile is limited to 10,000 and the number of actions across profiles in a system is limited to 50,000.

Ensure the above conditions are met before LSWU.

Flexible Policy Adaptor Profile

NOTE:  Flexible Policy is not supported on ERE and is intended for use with an external PSX only.


A SIP adapter profile can also be configured to support a flexible policy mechanism to facilitate dynamic routing and policy decisions based on any SIP message information element whereby routing and policy selection criteria are provisioned by the operator. An information element can be anything in the message, such as the following examples:

  • SIP header value
  • Presence or absence of a header
  • String in a message body
  • Parameter value
  • Presence or absence of a parameter

The following objects are used in supporting flexible policy and routing.

  • The Profile Type parameter is used to specify whether a SIP adapter profile is used for flexible policy or message manipulation (default).

  • The System Provisioning - Zone object is used to assign a flexible policy-specific SIP adapter profile to a specific zone.

  • The Trunk Group - SIP Trunk Group object is used to assign a flexible policy-specific SIP adapter profile to a specific trunk group.

Info

For Flexible Policy and Routing feature implementation, refer to Flexible Policy and Routing Support.

For Flexible Policy and Routing best practices, refer to Configuring Dynamic Policies and Routing Using Flexible Policy and Routing Feature.

SMM Rules and Behavior

SMM Rules

The following general SIP Message Manipulation (SMM) rules apply when creating or editing SIP adapter profile.

 Table 1: SIP Adaptor Profile SMM Rules

CategoryRules
Profile 

To edit/modify a profile, you must disable the profile first to make the necessary modifications and then enable it.

Profile TypeTo specify whether a SIP adapter profile is to be used for flexible policy or message manipulation.
Rule
  • A profile must have at least one rule.
  • A profile may have up to 10,000 rules.
Criteria
  • At least one criteria is required.
  • No more than 20 criteria are allowed per rule.
  • At least one message criteria is required.
  • No more than one message criteria is allowed.
  • No more than one global variable criteria is allowed.
  • No more than one header criteria is allowed.

  • No more than one message body criteria is allowed.

  • No more than one parameter criteria is allowed.

  • If a parameter criteria is specified, a header criteria must also be specified.

  • No more than one token criteria is allowed.

  • If a token criteria is specified, a header criteria must also be specified.

  • No more than one  variable criteria is allowed.

Actions
  • At least one action is required.
  • No more than 128 actions are allowed per rule.

Criteria/Action Interaction

  • If an action modifies, deletes, stores or renames an object, you must also include a criterion to check for the presence of that object.

    For example, if you have an action that modifies a header, deletes a header, stores a header to a variable, or renames a header, you must also include a criterion to check for the presence of the header to be modified, deleted, stored or renamed. This same principal is true for other objects (Parameter, Token, Message Body and Variable) as well.

EMA SIP Adaptor Profile Window

To create and work with SIP adapter profiles, go to Configuration > System Provisioning > Category: Trunk Provisioning > SIP Adaptor (SMM) Profile or
All > Profiles > Signaling > SIP Adaptor Profile

The SIP Adaptor Profile window opens with any existing profiles listed.

Figure 1: SIP Adaptor Profile Window


The following tool options are offered across the top of the window:

  • View CLI – Use this option to view the CLI version of a selected SIP adapter profile. This is useful to help you understand how the profile is expressed in CLI format.
  • Edit Rule Sequence – Use this option to rearrange the rule sequence of a selected SIP adapter profile.
  • Assign SIP Adaptor Profile – Use this option to assign a selected SIP adapter profile to required trunk groups and zones.
  • Test SIP Adaptor Profile – Use this option to test a selected SIP adapter profile on variables and a sample SIP message you supply.
  • Copy SIP Adaptor Profile – Use this option to copy the values of a selected SIP adapter profile and create another SIP adapter profile with a different name.
  • New SIP Adaptor Profile – Use this option to build a new SIP adapter profile.

Except for the New SIP Adaptor Profile option, you must select a profile from the list to make the tool options available. Each tool opens in its own form on the window. More than one tool may be open at the same time.

To minimize a form, click the "-" symbol in the top left corner. To maximize it, click the "+" symbol. Click the "x" symbol to close the form.

Note:

In the SIP Adaptor Profile List, the delete option (X) is only available when the profile is disabled. 

To Create a SIP Adaptor Profile

Click New SIP Adaptor Profile to begin creating a new SIP adapter profile. The Create New SIP Adaptor Profile form opens.

Figure 2: Create New SIP Adaptor Profile Form

The Create New SIP Adaptor Profile form consists of four sections:

  • Name field – Use this field to assign a name to the SIP adapter profile. The length of the SIP adapter profile name can be up to 23 characters.
  • Profile Type field – Use this field to specify whether a SIP adapter profile is to be used for flexible policy or message manipulation.
  • Rule form consists of a numeric Rule list and Criteria and Action sub-sections. The criteria and action areas expand to provide additional parameters as you make your choices.
  • Footer area – Includes check boxes to enable the profile or to enable advanced SMM. 
Note:

Required fields are designated with an asterisk next to the field.

When you define criteria and action statements, it is quite common that when you make a selection, a new selection appears for you to define. For example, when defining a Message criteria and you choose "all response messages" in the for field, the field "with a response code" will appear with the choices "of" and "in the range". Selecting "of" then causes a blank field to appear for you to define the response code.

Tip

While creating or editing a SIP adapter profile, periodically click Save to save your progress.

Use the following table to define the Criteria and Action fields for rule 1 in the profile. For each rule, you can define one or more criteria, and one or more actions. Click Save to save the rule and add the profile to the SIP Adaptor Profile List.

Table 2: Rules Form Fields

Field/ControlDescription
NameEnter the SIP adapter profile name. The length of the SIP adapter profile name can be up to 23 characters.
Profile Type

When creating a SIP adapter profile, use this parameter to specify whether a SIP adapter profile is to be used for flexible policy or message manipulation.

  • messageManipulation (default): The SBC performs message manipulation based on this SIP adapter profile.
  • flexiblePolicy: The SBC performs dynamic policy and routing based on SIP message information elements as specified in this SIP adapter profile.
Criteria:
Type

Each criteria you define will include one or more criteria types. By default, the first criteria type is Message, so the minimum activity to define is to take an action against one or more messages.

Criteria Types include:

  • Message
  • Header
  • Parameter
  • Token
  • Variable
  • Global Variable
  • Message Body
Sub-fields

Type: Message

  • for:
    • all messages
    • all request messages
    • specific request messages
    • all response messages
    • specific response messages

Type: Header

  • if a header named: Specifies the name of the header.
  • is:
    • present
    • absent
    • present and equal
    • present and not equal

    • present and matches the regex
      NOTE: The option, present and matches the regex, is same as regexp numMatch match in CLI
      NOTE: To perform the equivalent of CLI's regexp numMatch notMatch action, use the same present and matches the regex option, but specify a no match condition in the regular expression.

  • for:
    • all header instances
    • a specific header instance
    • a range of header instances
    • a number of header instances

Type: Parameter

  • if a parameter of time:
    • user info
    • URI
    • generic
  • named: Specifies the name of the parameter.
  • is:
    • present
    • absent
    • present and equal
    • present and not equal

    • present and matches the regex
      NOTE: The option, present and matches the regex, is same as regexp numMatch match in CLI.
      NOTE: To perform the equivalent of CLI's regexp numMatch notMatch action, use the same present and matches the regex option, but specify a no match condition in the regular expression.

Type: Token

  • if the token of the type:
    • URI display name
    • URI user name
    • URI host name
    • URI scheme
    • URI host port

Type: Variable

  • if the variable:
    • Var1 to Var100
  • is:
    • present
    • absent
    • present and equal
    • present and not equal

    • present and matches regex
      NOTE: The option, present and matches the regex, is same as regexp numMatch match in CLI.
      NOTE: To perform the equivalent of CLI's regexp numMatch notMatch action, use the same present and matches the regex option, but specify a no match condition in the regular expression.

Type: Global Variable

  • if the global variable:
    • source IP address
    • source port
    • signaling port ID
    • local IP
    • local port
    • egress TG name
    • ingress TG name
  • is:
    • present
    • absent
    • present and equal
    • present and not equal

    • present and matches regex
      NOTE: The option, present and matches the regex, is same as regexp numMatch match in CLI.
      NOTE: To perform the equivalent of CLI's regexp numMatch notMatch action, use the same present and matches the regex option, but specify a no match condition in the regular expression.       

Type: Message Body

  • is:
    • present
    • absent

    • present and matches the regex
      NOTE: The option, present and matches the regex, is same as regexp numMatch match in CLI.
      NOTE: To perform the equivalent of CLI's regexp numMatch notMatch action, use the same present and matches the regex option, but specify a no match condition in the regular expression.

(additional fields) Additional fields will display to define request or response message types for the above two choices designated by "*".
Undo ButtonClick to undo your current edits and start over defining criteria.
Add Criterion Button

Click to add the criterion to the rule. The criterion displays in its final definition.

To re-edit the criterion, click the Edit button, make the change, and click Apply Edit button.

Action:
Default action

The default action is to "Apply actions to a specific header instance equal to header instance 1. Click the edit tool (pencil icon) to change among:

  • all header instances
  • a specific header instance (header instance 1-10, or last)
  • a range of header instances
Type

Type defines the portion of the message on which the action is taken. Types include:

  • Header
  • Parameter
  • Token
  • Message Body
  • Variable
  • Message
action sub-field

The type selected will determine the list of available actions. For example, the following list of actions appear for the Header type:

  • add a header
  • modify a header
  • store a header to a variable
  • store SIP Param
  • delete a header
  • rename a header
  • modify a header using a regular expression
  • write a header to the CDR

The Parameter type includes:

  • add a parameter
  • modify a parameter
  • store a parameter to a variable
  • store SIP Param
  • delete a parameter
  • modify a parameter using a regular expression
  • write a parameter to the CDR

The Token type includes:

    • add a token
    • modify a token
    • store a token to a variable
    • store SIP Param
    • delete a token
    • modify a token using a regular expression
    • write a token to the CDR

The Message Body type includes:

  • add a message body
  • modify a message body using a regular expression

The Variable type includes:

  • store to a variable
  • store Profile Name
  • append to a variable
  • modify a variable using a regular expression
  • write a variable to the CDR
  • store a trunkgroup name to a variable

The Message type includes:

  • Ignore a message
  • Reject a message
  • Teardown the dialog
  • Create a URI
  • Route Action on Crankback


Some actions include use of regular expressions as described below:


Regular expressions are based on the following W3C regular expressions pattern which is defined as a pattern, or sub-pattern, containing any white space or none white space string for up to 128 characters. The pattern can occur zero or one time.

"(((([\s\S])){0,128})){0,1}"

additional sub-fields

One or more additional fields can display to further define the action to take depending upon the action chosen in the field above.

For example, selecting Type "Parameter" and action "add a parameter" will produce three additional fields to be completed:

  • named
  • from the
  • of the type

Or, selecting Type "Message" and action "teardown the dialog" produces the following field to specify a numeric SIP response code:

  • with a response code

Or, selecting Type "Message" and action "Route Action on Crankback" will open a list with three possible choices of action:

  • Attempt Next Route
  • Skip Remaining Routes
  • Disconnect Call
Footer
EnabledClick to enable this profile. A profile must be disabled to be deleted.
Advanced SMM Enabled

Enable flag to apply advanced SMM logic, such as dialog stateful variables, to the following messaging:

  • INVITE
  • REGISTER
  • SUBSCRIBE 

NOTE: Dialog Stateful variables are not applied for the NOTIFY messages received prior to receiving 200 OK response to the Egress SUBSCRIBE.

For an example SMM rule, see How to Treat Hostpart Based on the Received Format.

To Edit a SIP Adaptor Profile 

Note:

You can modify the SMM rules on a live system when SMM rules are being applied. The existing rules continue to be applied. The new rules become active once committed. 

  1. Select a SIP adaptor profile from the SIP Adaptor Profile List. The Edit Selected SIP Adaptor Profile form opens. You can change, add, or delete the rules in the profile but you cannot change the name or type.
  2. To add another rule to the profile, click the next sequential number in the Rule list, for example, Rule 2, to open Criteria and Action sub-sections where you can define the additional rule. 
  3. To edit an existing rule in the profile click on the rule in the Rule list. The rule's current definition appears in the Criteria and Action sub-sections where you can edit the values. 
  4. Click Save to save your changes.

To Copy a SIP Adaptor Profile

  1. Select the SIP adaptor profile you want to copy from the SIP Adaptor Profile List.
  2. Click Copy SIP Adaptor Profile. The Copy Selected SIP Adaptor Profile form opens. Enter a new name and change or add to the parameters as needed.
  3. Click Save to save your changes.

To Edit Rule Sequence

  1. Select the SIP adaptor profile whose rules you want to reorder from the SIP Adaptor Profile List.

  2. Click Edit Rule Seque

  3. Rearrange the rule sequence by dragging and dropping the list items and then click Save.

To Assign SIP Adaptor Profiles

You can assign a selected SMM profile at the global, address context, zone, and SIP trunk group levels. You can assign a selected Flexible Policy profile at the SIP trunk group and zone levels.

  1. Select the SIP adaptor profile you want to assign to a trunk group or zone from the SIP Adaptor Profile List.

  2. Click Assign SIP Adaptor Profile. Depending on the profile type, either a Message Manipulation or Flexible Policy form opens.
    Figure 3: Assign SIP Adaptor Profile - Message Manipulation

  3. Select the trunk group, zone, or address context to which you want to assign the profile, or check the box in the Global section. 
  4. Click Save.

To Test a SIP Adaptor Profile

  1. Select the SIP Adaptor profile you want to test from the SIP Adaptor Profile List.

  2. Click Test SIP Adaptor Profile. Test SIP Adaptor Profile tool displays in the workspace.
    Figure 4: SIP Adaptor Profile Test Tool


  3. In Global Variable Values, enter any optional environment variables you want to apply during the test. Use the following formats:

    FieldConvention

    Source IP Address

    IPv4 or IPv6 formatted IP address

    Source Port

    Integer in the range of 0..4294967295

    Signaling Port ID

    Integer in the range of 0..4294967295

    Local IP Address

    IPv4 or IPv6 formatted IP address

    Local Port

    Integer in the range of 0..4294967295

    Egress Trunk Group Name

    1-23 characters (characters allowed:  +-.:@0-9A-Z_a-z)

    Ingress Trunk Group Name

    1-23 characters (characters allowed:  +-.:@0-9A-Z_a-z)

  4. Copy the SIP message you want to test from a browser or other source, and the paste it into the Input SIP Message window.
    Figure 5: Input SIP Message


  5. Click Test. The Selected SIP Adaptor Profile is applied to the SIP message, and the results are display in Output SIP Message. An example appears below.
    Figure 6: Test SIP Adaptor Profile Tool


To View the CLI 

  1. Select the SIP Adaptor profile whose CLI statements you want to view from the SIP Adaptor Profile List.
  2. Click View CLI. The View CLI form opens. An example appears below.
    Figure 7: View CLI Script Tool

To Store a SIP Trunk Group Name to a Variable

The following example uses a SIP Adaptor Profile to store a SIP trunk group name. The SBC Core provides interworking functionality between the call legs when only one leg of a call supports preconditions while the other leg does not. Preconditions interworking is triggered based on the presence/absence or value of a SIP information element (for example, a proprietary header or parameter). The message content is based on IP Trunk Group (IPTG)-related configurables on the ingress leg.

NOTE:

  • If Preconditions interworking is configured as “Use UPDATE”, configure the Allow UPDATE flag as well.
  • If Preconditions interworking is configured as “Use UPDATE” but a 183 from the peer does not have UPDATE in the Allow header, the SBC will not send an UPDATE and does not take any other action, thus a call timeout timer generates to terminate the call.
  • Do not set Preconditions to "Required" for interworking scenarios.

  • During an ingress precondition interworking scenario, if the remote precondition is met in PRACK, the SBC processes it and sends the INVITE towards the egress.

Note

Prior to configuring a SIP Trunk Group name to a variable, refer to Reserving Network Resources to understand the preconditions and the requirements. 

Follow these steps to assign a SIP trunk group name to a variable:

  1. Navigate to All > Profiles > Signaling > IP Signaling Profile > Common IP Attributes > Preconditions. The Preconditions window is displayed. Refer to IP Signaling Profile - Common IP Attributes - Preconditions to know the parameters and their descriptions.
  2. Choose the DEFAULT_SIP IP signaling profile or any of your created signaling profiles.

  3. Click to enable its State. The other parameters/flags become available.

  4. Enable/disable the following parameters:
    1. Support If Egress IPTG - Disable
    2. Strength Mandatory Policy - Enable
    3. Strength Optional Policy - Enable
    4. UPDATEPreconditions Policy - Disable
    5. Strength Mandatory Priority - 10
    6. Strength Optional Priority - 45
    7. UPDATEPreconditions Priority - 56
  5. Click Save.

  6. Navigate to Configuration > System Provisioning > Category: Trunk Provisioning > SIP Adaptor (SMM) Profile. The SIP Adaptor (SMM) Profile window is displayed.

  7. Fill in the following information:
    1. Name - Name of the SIP Adaptor Profile that is created.
    2. Profile Type - messageManipulation
    3. Criteria:
      Type - Message
      for - specific request message
      of the type - invite
    4. Action:
      Type - Variable
      store a trunk group name to a variable
      Store the - String
      with the value - <name of the string to store> for example: TG_SIP_Access2
      to the - local variable
      named - var1
  8. Click Add criterion and Add action to save the information.
  9. Click Save.