Contents

1   Introduction

This document describes how to configure the Communication Setup Announcement (CSA) service in the MTAS.

1.1   Prerequisites

It is assumed that the user is familiar with the Operation and Maintenance (O&M) area, in general.

1.1.1   Licenses

To enable basic services in the MTAS, the MMTel AS Voice Base license must be installed.

For more information about the MTAS licenses, refer to MTAS Licenses.

1.1.2   Documents

Before starting any procedure in this document, ensure that the following documents are available:

• Ericsson Command-Line Interface User Guide
• Managed Object Model (MOM)

1.1.3   Conditions

The following condition must apply:

• An Ericsson Command-Line Interface (ECLI) session in Exec mode is in progress.

2   Overview

CSA is an originating MMTel AS rule based service that plays configured announcement to served user for outgoing call setup based on evaluation of operator provisioned service rules.

The main use cases of this function are as follows:

• Play announcement
• Manage subscription of CSA operator rules
• Configure CSA on node-level

CSA is a rule-based announcement service, which means that CSA evaluates rules to determine if a communication setup announcement is to be played. The function is executed only at the originating MTAS.

CSA triggers the Play announcement subfunction on initial outgoing INVITE to play audio, or video announcements, or both, for the caller when the rule is matched. It supports playing generic announcement. For further details, see Section 2.2.3 Play Announcement.

2.1   License Control

There is no license needed to enable the CSA service and to evaluate conditions in operator rules. However, to enable basic services in the MTAS, the MMTel AS Voice Base license must be installed. For more information about the MTAS licenses, refer to MTAS Licenses.

2.2   Subfunctions

2.2.1   Manage Subscription Data

This subfunction allows management of subscriber data, to create, update, and delete. For more information, see Section 4.4 Service Data Management.

2.2.2   Rules Evaluation

This subfunction evaluates the subscription rules and conditions of the served user, that can result in playing announcement.

2.2.3   Play Announcement

The CSA service evaluates service rules and play announcement towards served user on outgoing INVITE before continuing call establishment.

CSA supports playing generic announcement by operator-named announcement indicated in the play-announcement action element within the matched CSA rule.

The CSA service does not support provisioning of announcement segments.

For more information about generic announcement handling for the CSA service, refer to MTAS Generic Announcement Management Guide.

2.2.4   Configure Service

This subfunction is the CM part of the CSA service, see Section 4 CSA Service Configuration.

2.2.5   Update PM Counter

CSA updates specific PM counters, which reflects successful and unsuccessful invocations.

2.3   Interaction with Other Services

2.3.1   Charging

The use of the CSA service is reported in charging messages generated during the setup of an MMTel session only when the CSA successfully triggers announcement after rule evaluations.

For more information about the Charging service, refer to Diameter Offline Charging in MTAS and Diameter Online Charging in MTAS.

2.3.2   Communication Barring

Communication setup announcement is only triggered when Outgoing Communication Barring (OCB) accepts call setup.

For Incoming Communication Barring (ICB), the CSA service is not applicable as it is an originating service.

For more information about the Communication Barring (CB) services, refer to MTAS Barring and Dial Plan Services Management Guide.

2.3.3   OCT

In originating MMTel AS, when a user starts the Operator Controlled Transfer (OCT) service by dialing to the directory service, CSA is started during a session with the Operator Transferor (OT) and also following a redirection from OT.

For more information about the OCT service, refer to MTAS Operator Controlled Transfer Management Guide.

2.3.4   Communication Diversion

CSA is not started when call is diverted for the served user.

For more information about the Communication Diversion (CDIV) service, refer to MTAS Communication Diversion Management Guide.

2.3.5   Flexible Communication Distribution

CSA is not started at related user distribution.

For more information about the Flexible Communication Distribution (FCD) service, refer to MTAS Flexible Communication Distribution Management Guide.

2.3.6   STOD

CSA is not started when the session is transferred after Session Transfer to Own Device (STOD) invocation for served user.

For more information about the STOD service, refer to MTAS Session Transfer to Own Device Management Guide.

2.3.7   3PTY

CSA is not started when a 3PTY session is created for served user.

For more information about the 3PTY service, refer to MTAS Three Party Management Guide.

2.3.8   Ad-hoc Conference

CSA is not started when participant is invited when served user is Conference Creator.

For more information about the conference service, refer to MTAS Ad-hoc Conference Management Guide.

2.3.9   Flexible Service Format Selection

In the originating MMTel AS, Communication Setup Announcement service can be suppressed by the Flexible Service Format Selection (FSFS) service.

For more information about the FSFS service, refer to MTAS Flexible Service Format Selection Management Guide.

3   Subscription Rules

The subscription rules are expressed with XML, defined by a schema, and follow the structure illustrated in Figure 1.

The rule set consists of zero or many rules, and one rule consists of zero or many conditions and one action.

The element Rule has one attribute id that identifies the rule. The id attribute has nothing to do with the evaluation order.

The top-level CSA element has an attribute active of type Boolean. If active=true then the rule set is evaluated.

The different conditions that apply to CSA are as follows:

• cp:validity
• ss:rule-deactivated
• mmt-serv:valid-periods
• mmt-serv:invalidity
• cp:identity
• mmt-serv:served-identity
• media
• mmt-serv:in-sip-request
• mmt-serv:subscriber-state

3.1   cp:validity

Specifies one of more periods. The condition evaluates to TRUE when the current time is within the validity period expressed by one of the time periods included in this condition. In all other cases, the condition evaluates to FALSE.

It expresses the rule validity period by two attributes, a starting and an ending time. The validity condition is TRUE if the current time is greater than or equal to at least one <from> child, and less than the <until> child after it.

The format is XML dateTime. Its canonical representation is UTC and time zones are expressed as a positive or negative duration (2005-12-24 12.00 in Stockholm, GMT+1, is expressed as 2005-12-24T12:00:00+01:00 and has the corresponding canonical representation 2005-12-24T11:00:00Z).

Note:  

To set date later than year 2036 is not supported on TSP and the value is not correctly handled.

When the validity period is given in local time format, the UTC offset is taken from the <user-common-data>. If the UTC offset is not provisioned for the user, the value from the CM attribute mtasMmtCalUtcOffset is used.

Times in cp:validity conditions are converted to UTC before being compared to the current time, also in UTC. This is shown in the following example:

<cp:validity>
<!-- This example shows time being defined as an offset from UTC-->
     <cp:from>2008-10-12T20:00:00-08:00</cp:from>
     <cp:until>2008-10-19T19:59:59-08:00</cp:until>
     <!-- example in UTC as shown by the Z -->
     <cp:from>2008-11-27T20:00:00Z</cp:from>
     <cp:until>2008-11-28T08:00:00Z</cp:until>
</cp:validity>

For more information about the configuration of time-based services in MTAS, refer to MTAS Time Based Services Management Guide.

3.2   ss:rule-deactivated

This condition always evaluates to FALSE. This can be used to deactivate a rule, without losing information. By removing this condition, the rule can be activated again.

3.3   mmt-serv:valid-periods

Allows the assembly of complex time condition based on the following elements and sub conditions:

• times of day (in form of intervals, like 09:00-12:00)
• days of the week (for example Monday)
• workdays/non-workdays (use of pre-provisioned/configured list of weekdays)
• private and public holidays (for example Monday)
• days of the month (for example, first day, last day, first Wednesday, the 13th)
• calendar months
• calendar weeks
• daily, weekly, and monthly repetitions (with start day and repetition interval)

Note:  

Setting the date later than year 2036 is not supported on TSP.

If any element within the subconditions evaluates to TRUE, then the subcondition evaluates to TRUE. The mmt-serv:valid-periods evaluates to TRUE only when all the included subconditions evaluates to TRUE.

The mmt-serv:valid-periods evaluates to TRUE only when all the included subconditions evaluates to TRUE.

It is also possible to mark the holidays as exception for the whole mmt-serv:valid-periods condition. So, when the current day is holiday, then the mmt-serv:valid-periods evaluates to FALSE.

For more information on the other provisioned and configured data used at evaluation of mmt-serv:valid-periods, refer to MTAS Time Based Services Management Guide.

For more information about the subconditions, refer to MTAS Time Based Services Management Guide.

3.4   cp:invalidity

Specifies one of more periods. The condition evaluates to false when the current time is within the validity period expressed by one of the time periods included in this condition. In all other cases, the condition evaluates to TRUE.

It expresses the rule invalidity period by two attributes, a starting and an ending time. The invalidity condition is FALSE if the current time is greater than or equal to at least one <from> child, and less than the <until> child after it. The invalidity condition is TRUE only when the current time is not within any of the invalidity periods.

The format is XML dateTime. Its canonical representation is UTC and time zones are expressed as a positive or negative duration (2005-12-2412.00 in Stockholm, GMT+1, is expressed as 2005-12-24T12:00:00+01:00 and has the corresponding canonical representation 2005-12-24T11:00:00Z).

When the invalidity period is given in local time format, the UTC offset is taken from the <user-common-data>. If the UTC offset is not provisioned for the user, the value from the CM attribute mtasMmtCalUtcOffset is used.

Times in mmt-serv:invalidity conditions are converted to UTC before being compared to the current time, also in UTC.

For more information about the configuration of time-based services in MTAS, refer to MTAS Time Based Services Management Guide.

3.5   cp:identity

This condition evaluates to TRUE when the called user’s identity matches with the value of the identity element. In all other cases, the condition evaluates to FALSE.

The interpretation of the special case of a <number-match> element is described here. The interpretation of all the other elements of this condition is described in the IETF RFC 4745 specification.

CSA matches content of the Request URI with this condition.

The input URI is only considered equal to the <one id> or <except> element in the cp:identity condition (the rule URI) if the number parts match and the parameters satisfy the following conditions:

• If there is a phone-context=pvalue parameter in the rule URI, there must be an identical phone-context=pvalue parameter in the input URI.
• If there is no phone-context parameter in the rule URI, there must be no phone-context parameter in the input URI.
• If there is an ext=phonedigits parameter in the rule URI, there must be an identical ext=phonedigits parameter in the input URI.
• If there is no ext parameter in the rule URI, any ext parameter in the input URI is ignored.
• If there is an isub=subaddress parameter in the rule URI, there must be an identical isub=subaddress parameter in the input URI.
• If there is no isub parameter in the rule URI, any isub parameter in the input URI is ignored.

Any other parameters are ignored.

For CSA, the input URI is considered to match the <number match> element in the cp:identity condition (the rule URI) if the first few characters of the number part of the input URI match all the characters in the rule URI. Parameters cannot appear in the <number match> element, so any parameter in the input URI is ignored.

The comparison of SIP URIs is based on section 19.1.4 in the IETF RFC 3261 specification.

However, only the user and host parts of SIP URIs are considered when comparing for CSA, that is, the password, port, URI parameters, and headers are ignored for comparing SIP URIs for CSA. For a SIP URI that was converted from a tel URI, the user part of the SIP URI contains the number and parameters of a tel URI, so the comparison must first consider the host part of the SIP URI, and then must treat the user part as if it was a tel URI.

3.6   mmt-serv:served-identity

This condition evaluates to true when one of its mmt-serv:one subelements match the served user’s identity.

The mmt-serv:one sub elements are interpreted similar to the sub elements of cp:identity.

CSA matches content of:

• The P-Served-User header field, if present.
• If P-Served-User not present, then P-Asserted-Identity
• If not PSU and PAI then From-header is used.

If the served user cannot be determined, service rules using the served-identity condition are ignored.

3.7   Media

This condition evaluates to TRUE when the value of this condition matches the media field in one of the m= lines in the SDP offered in the INVITE.

3.8   mmt-serv:in-sip-request

This condition is an assembly of regular-expressions subconditions on a SIP request triggering a given rule. A header parameter can be matched directly or inversely. Sub conditions used in service rules must be predefined by operator in the User Common Data. The condition evaluates to TRUE if all of its subconditions evaluate to TRUE.

3.9   mmt-serv:subscriber-state

The mmt-serv:subscriber-state condition is evaluated to true when the operator-configured mmt-serv:subscriber-state in the CSA is matched with the operator-provisioned subscriber-state in the mmt-op:subscriber-state. The mmt-op:subscriber-state is provisioned in the mmt-op:operator-common-data. When the condition is present in the rule, it specifies the value that the generic purpose subscriber state from operator’s common-data need to match. If the value is matched, the condition is satisfied. If the condition is omitted, then the condition applies to all the subscriber states.

4   CSA Service Configuration

The CSA function of the MTAS is controlled by the MtasCsa MOC.

The structure of CSA MOC is described in Figure 2.

For configurable MOs and attributes related to the CSA service, refer to Managed Object Model (MOM).

4.1   Announcement Configuration

The CSA plays an audio or video announcement, or both, to the caller before communication setup continues.

For announcement handling and CSA announcement attributes, refer to MTAS Announcement Management Guide.

4.2   CSA Administrative State Configuration

The CSA service is enabled by setting the mtasCsaAdministrativeState attribute in the MtasCsa MO to 1 (UNLOCKED).

If the mtasCsaAdministrativeState is set to 0 (LOCKED), no CSA service is provided by the MTAS.

4.3   Wholesale for CSA Configuration

The CSA service supports Wholesale. CSA is configurable on Virtual Telephony Provider level.

Wholesale for CSA is activated when the following attributes are set to 1 (UNLOCKED):

• The vtasCsaAdministrativeState attribute in the VtasCsa MO.
• The mtasCsaAdministrativeState attribute in the MtasCsa MO.

For more information about the Wholesale service, refer to MTAS Wholesale Support Management Guide.

4.4   Service Data Management

4.4.1   Operator Subscription Level Service Configuration

The operator can activate or deactivate the CSA service subscription for the subscriber by providing or removing the CSA XML structure in the Subscriber Data of the operator.

For more information about the CAI3G protocol and XML Schema Definition, refer to MTAS CAI3G Interface.

4.4.2   Subscriber Subscription Level Service Configuration

There is no user subscription level service configuration (Ut interface) defined for the CSA service.

The Ut interface and the XML schema for the Ut interface are described in MTAS Ut Interface and MTAS Ut Structure.

5   Performance Management

For measurements related to the CSA service, refer to MTAS Performance Measurements.

6   Fault Management

The CSA service has no alarms.

7   Example Configuration

7.1   CSA Rules Examples

To guarantee its uniqueness, a namespace can often be a long unwieldy string. XML allows a namespace to be mapped to a short string (a prefix), which makes XML documents more readable. Table 1 shows the mapping between each namespace and its assigned prefix, as used in this example.

7.1.1   Play Announcement Based on Subscriber-State

In this example, the following conditions apply:

• The subscriber makes an outgoing call.
• The subscriber-state is Notification.
• The operator-configured rule for the subscriber-state is Notification.

If a match is found: an announcement is played, if configured, and call setup continues after the announcement.

<mmt-data:operator-service-data>
<mmt-op:operator-communication-setup-announcement activated='true'>
<cp:ruleset>
<cp:rule id='totalsuspension'>
<cp:conditions>
<mmt-serv:subscriber-state>TotalSuspension</mmt-serv:subscriber-state>
</cp:conditions>
<cp:actions>
<mmt-serv:play-announcement>TotalSuspensionAnn</mmt-serv:play-announcement>
</cp:actions>
</cp:rule>
<cp:rule id='halfsuspension'>
<cp:conditions>
<mmt-serv:subscriber-state>HalfSuspension</mmt-serv:subscriber-state>
</cp:conditions>
<cp:actions>
<mmt-serv:play-announcement>HalfSuspensionAnn</mmt-serv:play-announcement>
</cp:actions>
</cp:rule>
<cp:rule id='notification'>
<cp:conditions>
<mmt-serv:subscriber-state>Notification</mmt-serv:subscriber-state>
</cp:conditions>
<cp:actions>
<mmt-serv:play-announcement>NotificationAnn</mmt-serv:play-announcement>
</cp:actions>
</cp:rule>
</cp:ruleset>
</mmt-op:operator-communication-setup-announcement>
</mmt-data:operator-service-data>
<mmt-op:operator-common-data>
<mmt-op:subscriber-state>Notification</mmt-op:subscriber-state>
</mmt-op:operator-common-data>

7.1.2   Play Announcement Based on Multiple Rules with Combined Conditions

In this example, there are multiple rules each of them have multiple conditions. These are evaluated when a subscriber makes an outgoing call.

• When the subscriber supports both audio and video as Media and Validity condition is true.
• When the subscriber makes a call during the Valid-Period and out of invalidity range.
• When the subscriber is "sip: +4612341111@operator.com".
• When the subscriber prefers video call for outgoing calls.

If a match is found: an announcement is played, if configured, and call setup continues after the announcement.

<mmt-data:operator-configuration>
   <mmt-data:operator-service-data>
 <mmt-op:operator-user-common-data activated="true">
     <mmt-op:in-sip-request-condition activated="true" />
      <mmt-op:in-sip-request-condition-list>
       <mmt-op:flexcondition id="video caller preference" header="Accept-Contact"
 parameter="video" match-inverse="false" value="^true$" />
       <mmt-op:flexcondition id="audio caller preference" header="Accept-Contact"
 parameter="audio" match-inverse="false" value="^true$" />
     </mmt-op:in-sip-request-condition-list>
    </mmt-op:operator-user-common-data>
    <mmt-op:operator-communication-setup-announcement activated="true">
         <cp:ruleset>
      <cp:rule id="csa-rule-deactivated-identity">
       <cp:conditions>
          <ss:rule-deactivated/>
            <mmt-serv:identity>
              <mmt-serv:one id="sip:411@operator.com" />
            </mmt-serv:identity>
       </cp:conditions>
       <cp:actions>
         <mmt-serv:play-announcement>411 announcement</mmt-serv:play-announcement>
       </cp:actions>
      </cp:rule>
    <cp:rule id="csa-complex-media-validity">
      <cp:conditions>
        <ss:media>video</ss:media>
        <ss:media>audio</ss:media>
        <cp:validity>
      <!-- This example shows time being defined as an offset from UTC-->
          <cp:from>2008-10-12T20:00:00-08:00</cp:from>
          <cp:until>2008-10-19T19:59:59-08:00</cp:until>
          <!-- example in UTC as shown by the Z -->
         <cp:from>2008-11-27T20:00:00Z</cp:from>
          <cp:until>2008-11-28T08:00:00Z</cp:until>
        </cp:validity>
       </cp:conditions>
     <cp:actions>
      <mmt-serv:play-announcement>Video Greeting</mmt-serv:play-announcement>
       </cp:actions>
     </cp:rule>
      <cp:rule id="csa_valid_periods_invalidity">
        <cp:conditions>
         <mmt-serv:valid-periods except-holidays="true">
           <mmt-serv:valid-days>
             <mmt-serv:day>Thursday</mmt-serv:day>
              </mmt-serv:valid-days>
             <mmt-serv:valid-weeks>20</mmt-serv:valid-weeks>
            <mmt-serv:valid-months>
              <mmt-serv:month>05</mmt-serv:month>
              </mmt-serv:valid-months>
              <mmt-serv:repeat-daily>
              <mmt-serv:begin-day>2018-05-10T11:04:02+02:00</mmt-serv:begin-day>
              <mmt-serv:repeat-interval>7</mmt-serv:repeat-interval>
            </mmt-serv:repeat-daily>
           <mmt-serv:repeat-weekly>
            <mmt-serv:begin-day>2018-05-10T11:04:02+02:00</mmt-serv:begin-day>
            <mmt-serv:repeat-interval>1</mmt-serv:repeat-interval>
           </mmt-serv:repeat-weekly>
           <mmt-serv:repeat-monthly>
            <mmt-serv:begin-day>2018-04-17T11:04:02+02:00</mmt-serv:begin-day>
            <mmt-serv:repeat-interval>1</mmt-serv:repeat-interval>
           </mmt-serv:repeat-monthly>
          <mmt-serv:valid-monthdays>
            <mmt-serv:monthday>17</mmt-serv:monthday>
            </mmt-serv:valid-monthdays>
         </mmt-serv:valid-periods>
            <mmt-serv:invalidity>
       <mmt-serv:from>2018-05-15T11:04:02+02:00</mmt-serv:from>
      <mmt-serv:until>2018-05-16T11:04:02+02:00</mmt-serv:until>
       </mmt-serv:invalidity>
        </cp:conditions>
          <cp:actions>
            <mmt-serv:play-announcement>Happy Thursday</mmt-serv:play-announcement>
         </cp:actions>
      </cp:rule>
     <cp:rule id="csa-served-identity">
      <cp:conditions>
        <mmt-serv:served-identity>
          <mmt-serv:one id="sip:+4612341111@operator.com" />
           </mmt-serv:served-identity>
           </cp:conditions>
           <cp:actions>
            <mmt-serv:play-announcement>Premium Customer Service</mmt-serv:play-announcement>
           </cp:actions>
         </cp:rule>
       <cp:rule id="csa-sip-regexp">
         <cp:conditions>
           <mmt-serv:in-sip-request>
             <mmt-serv:flexcondition id="video caller preference" />
               </mmt-serv:in-sip-request>
            </cp:conditions>
           <cp:actions>
             <mmt-serv:play-announcement>Video Call preferred</mmt-serv:play-announcement>
           </cp:actions>
          </cp:rule>
     </cp:ruleset>