Cisco BTS 10200 Softswitch Operations and Maintenance Guide, Release 6.0.4

FIM/XML

This appendix describes the FIM/XML feature of the Cisco BTS 10200 Softswitch and explains how to use it. This document includes the following topics:

•Understanding the Configurable FIM/XML Feature

•Tool Requirements

•Writing an External FIM/XML File

•Defining Features

•Installing the FIM/XML File Using the Offline FIM/XML Tool

•FIM/XML File and Shared iFC File

•Provisioning iFC

•Feature Restrictions and Limitations

Understanding the Configurable FIM/XML Feature

The Cisco BTS 10200 supports a Feature Interaction Module/Extensible Markup Language (FIM/XML) file that defines the interactions between the internal features (for example, Call Waiting, Call Forwarding) and external features (features that reside on application servers that interact with Cisco BTS 10200 and SIP triggers like, TV Caller ID, Network Address Book).

However, the current FIM/XML format can be time consuming as the service provider or operator needs to configure and define large number of parameters. The configurable FIM/XML feature introduces a new external configurable FIM/XML file which is more efficient because it defines the interactions between the IMS Service Control Interface (ISC) and Feature Control Protocol (FCP) features. The Cisco BTS 10200 Feature Server manages the ISC and FCP feature interactions based on the rules in this FIM/XML file.

The Cisco BTS 10200 Softswitch Plain Old Telephone Service (POTS) Feature Server uses the configurable FIM/XML file to manage the ISC and FCP features using the parameters defined in the configurable FIM/XML file. You can produce the new FIM/XML file using the old FIM/XML file and schema data.

External FIM/XML file allows you to do the following:

•Add a new external feature name

•Specify the list of features inhibited by an external feature

•Specify the precedence order for the external features

•Define the list of features that inhibit the external feature

•Define error response operations

Advantages of the FIM/XML Tool

The FIM/XML tool enables the service provider or operator to specify the SIP trigger-based features. The SIP trigger-based feature examples are, Off-Hook Delay Trigger (OHD), Termination Attempt Triggers TAT-1 and TAT-2.

The tool helps to define the interactions and precedence with the other features of Cisco BTS 10200. The service provider can generate his or her own XML file (FIM/XML) according to the schema data provided in the Cisco BTS 10200. Once the generated FIM/XML file is installed on the Cisco BTS 10200, the new external application server-driven features and their interactions with other Cisco BTS 10200 features comes into effect.

The advantages of the FIM/XML tool are:

•The tool prevents the operator from the possibility of disrupting the external/current features when editing the complex FIM/XML file. The FIM/XML tool now provides an easy and efficient way of editing the complex file seamlessly.

•Provides a semantic check on the operator-generated FIM/XML file.

In order to specify a common SIP trigger profile, an additional XML file needs to be generated. This XML file calls the Shared Initial Filter Criteria (iFC) XML file read by Cisco BTS 10200 to determine the SIP trigger profiles. SIP trigger profiles are used to determine the address of the application server and populate the different route-headers when SIP triggers launch. For additional information on the shared iFC file, refer to the "FIM/XML File and Shared iFC File" section.

Tool Requirements

Each Cisco BTS 10200 release includes an original FIM/XML file. The offline FIM/XML tool allows the service provider or operator to define a new external feature or modify existing interactions involving the ISC features.

The Cisco BTS 10200 must meet the following conditions and requirements for the FIM/XML tool:

•Java Virtual Machine (JVM) 1.6 or above is installed on the system.

•All three input files (for example param=1, param=2, and param=3) are present in the same directory as the tool .jar file. Refer to Step 6 in the procedure below for the list of input files.

•The service provider or operator has write permission for the directory where the FIM/XML offline tool is located.

•The service provider or operator has read permission for all the input XML files.

Writing an External FIM/XML File

To write an external FIM/XML file, do the following:

Step 1 Use any XML editor.

Step 2 Open a new XML file in it.

Step 3 Set the schema to the supplied External FIM/XML schema:

<external-fimxml xsi:schemaLocation="externalfimxml externalfimxml.xsd" 
xmlns="externalfimxml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> 

Step 4 Define new features in XML file.

Step 5 Save the new external FIM/XML file.

Defining Features

The service provider needs to define new features to ensure that Cisco BTS10200 understands the behavior of the external features. The external feature is defined using the define-external tag in the External FIM/XML file:

<define-external feature-name="TAT_5"feature-type="TERMINATING">

</define-external> 

Each external feature has a unique name. The name has a minimum of 16 characters, and no special characters are allowed. The Feature Type is defined as Originating or Terminating.

Elements in the External FIM/XML File

The external FIM/XML is a subset of the FIM/XML file and contains definitions and behavior of ISC features. The External FIM/XML file is used to define the ISC feature and its properties. The defined external elements are used to add new external features to Plain Old Telephone System (POTS) FC.

The external FIM/XML file contains the following elements:

•"Define Element" section

•"Precedence-Exception Element" section

•"Inhibit Others Element" section

•"Inhibit Me Element" section

•"Response Profile Element" section

Define Element

The properties of the external feature are configured in the Define Element. The FIM/XML tool processes the external FIM/XML file in the Define Element.

<define-external feature-name="TAT_1" precedence_lesser_than ="SCR" 
billing-name="tat1_as">

Table 1 lists the attributes in the Define Element.

Precedence-Exception Element

The Precedence-Exception element defines the exception in the precedence list for the defined external feature. The feature name in the precedence-exception element has a lesser precedence than the defined external feature even after the external feature is defined below it in the precedence list.

The following is the example to define precedence exception:

<define-external feature-name="F5" precedence-lesser-than="F4" >

<precedence-exception feature-name="F2"/>

....

</define-external> 

You can have as many exceptions for the precedence as you like (for example, F1>F2>F3>F4>F5>F2, where you can define F5 precedence less than F4 and greater than F2).

Table 2 lists the attributes of the Precedence-Exception Element.

The FIM/XML tool expects the Precedence-Exception element in External FIM/XML file as follows.

<precedence-exception feature-name="CCW" />

Inhibit Others Element

The Inhibit Others Element tag defines the list of features that are inhibited when a given feature is in an Assigned or Invoked state. Table 3 lists the attributes of the Inhibit Others Element.

Feature Inhibitions prevent invocation of a given feature if a specified feature is Activated, Deactivated, Invoked, Assigned. For example, when the emergency call is involved then the Call Waiting is inhibited.

The FIM/XML tool expects the defined element in the External FIM/XML file as indicated in the following sections.

<inhibit-others state="ASSIGNED" feature-name="CNAM"/>

<inhibit-others state="INVOKED" feature-name="MOH"/>

Inhibit Me Element

The Inhibit Me element defines the list of features that inhibit the external feature when the features are in the following states: Activated, Deactivated, Assigned, or Invoked. Table 4 lists the attributes of the Inhibit Me Element.

The FIM/XML tool expects the defined element in the External FIM/XML file as indicated in the following sections.

<inhibit-me feature-name="CCW" state="DEACTIVATED"/>

<inhibit-me feature-name="CW" state="INVOKED"/>

Response Profile Element

When the defined external feature is invoked, the system receives different responses or errors, depending on what happened during the feature invocation. This allows the operator to specify what actions need to be taken when specific errors or responses (SIP Responses) are received from the Application Servers.

For example, when an external feature is invoked, an INVITE is sent by Cisco BTS 10200 to the Application Server and no application server can return an error response such as "401 unauthorised" error. You can define the action that Cisco BTS 10200 can take using the Response Profile element.

Error

The list of error elements is matched one by one to see if the error response received during the external feature invocation falls within its specified range. When a match is found, the error handling operation specified within the respective error element is executed.

Operation

This element specifies the action taken when the response condition matches the error element. The parameters of an element can be a list of name or value pairs specified by parameter elements.

The FIM/XML tool processes the defined element in the External FIM/XML file as indicated in the following sections.

		<response-profile>

			<error range-start="503" range-end="599" type="SIP">

				<operation name="continue-from-dp"/>

			</error>

	<error range-start="403" range-end="403" type="SIP">

				<operation name="disconnect">

					<param name="cause" value="1325"/>

				</operation>

			</error>

		</response-profile>

Installing the FIM/XML File Using the Offline FIM/XML Tool

Each Cisco BTS 10200 release includes an original FIM/XML file that is installed during system setup and upgrades. The offline FIM/XML tool allows the service provider to define a new external feature or modify existing interactions involving the ISC features. In order to enable the service provider to add external features, a separate XML configuration file is provided. This new FIM/XML file is called an External FIM/XML file. After the operator generates the external FIM/XML file according to the schema provided, the FIM/XML tool generates the FIM/XML file. Use this file as input, along with the schema, to produce the new FIM/XML file with the offline tool. The offline tool is the XML file that is separate from the Cisco BTS 10200.

Note The system must meet the tool conditions and requirements for the FIM/XML tool as described in "Tool Requirements" section.

The following procedure describes how to generate the configurable FIM/XML file using the offline FIM/XML tool.

Step 1 Obtain the fiexmxml.zip file from the location specified and then unzip the FIM/XML file on all BTS nodes:

/opt/OptiCall/tools/fiexmxml.zip

Step 2 Run the fimxml.zip file.

The external FIM/XML template is external.xml and the external FIM/XML schema is obtained as externalfimxml.xsd:

hrn29priems:/opt/OptiCall/tools >unzip fimxml.zip

Archive:  fimxml.zip

  inflating: config.xml

  inflating: external.xml

  inflating: externalfimxml.xsd

  inflating: fimxmlconfig.xsd

  inflating: FIMXML.xsd

  inflating: fimxml.jar

hrn29priems:/opt/OptiCall/tools 

Step 3 Use any XML editor to create an external FIM/XML file based on the rules from the externalfimxmlfile.xsd schema file provided by the Cisco BTS 10200 during installation. The service provider cannot modify the schema data.

Step 4 Use the XML editor to edit a sample file provided with the FIM/XML tool. This file becomes the offline FIM/XML configuration file used in Step 6.

Step 5 You can edit the FIM/XML file so that the emergency features such as 9-1-1, Hostage Negotiation, and Emergency Callback (ECB) cannot be inhibited by the operator after the configurable FIM/XML file is downloaded to the Cisco BTS 10200:

<fcp-features> <feature name=E911 inhibition-allowed=false/> 

You can also configure the schema path for the configurable FIM/XML file:

<config-param param=FIMXMLSCHEMA_PATH value=FIMXML.xsd/>

If you do not specify a schema path, the Cisco BTS 10200 uses the following default path:

/opt/OptiCall/potsctx/bin/FIMXML.xsd

Step 6 Run the following Java application:

java —jar fimxml.jar param1 param2 param3 param4 

Where

•param1 = the name of the external FIM/XML file described in Step 3

•param2 = the name of the original FIM/XML file produced during the Cisco BTS 10200 installation. Copy this file from the following path: /opt/OptiCall/etc/fimxml/FSPTC235/FIMXMLRules.xml.

•param3 = the name of the configuration file described in Step 4

•param4 = the name of the configurable file to be generated (defaults to merged.xml). This parameter is optional.

If the script runs successfully, the tool returns the following message SUCCESS!! New FIM/XML generated at path <path>. The successfully generated configurable FIM/XML files are copied or FTP to the EMS.

If the script does not complete successfully, the system returns a non-zero value and generates a log file which is copied to the same directory as the FIM/XML tool .jar file.

Note The tool produces log files for both successful and unsuccessful attempts.

Note You can troubleshoot the errors from the descriptions provided with the error messages.

Step 7 Run the following command from the EMS:

install fimxml file_name=<absolute_path> 

This command does the following:

•Processes the configurable FIM/XML file on the EMS

•Adds, updates and/or deletes the external feature names from the new fimxml file.

•Copies the new file to the following path:
/opt/OptiCall/etc/fimxml/FSPTC235/FIMXMLRules.xml

Step 8 Restart the POTS Feature Server on both the CA primary and secondary nodes to load the configurable FIM/XML file.

FIM/XML File and Shared iFC File

A Shared Initial Filter Criteria (iFC) file specifies all the data required to provision a new feature in the Element Management System (EMS). Using the shared iFC file is analogous to provisioning feature data through the CLI. You can provision all the user commands supported through CLI using the shared iFC.

The Cisco BTS 10200 supports the following commands through shared iFC:

•Add/change/delete feature

•Add/change/delete feature-config fname

•Add/ change/delete vsc

•Add/change/delete sip-trigger-profile

•Add/Change/delete subscriber-sip-trigger-profile

•Add/Change/Delete service

•Add/Change/Delete subscriber-service-profile

The following conditions apply to the configurable FIM/XML file and the shared iFC file:

•Any property provisionable through FIM/XML cannot be provisioned through the shared iFC file.

•If an external feature name exists in the FIM/XML file but is not defined in the EMS, then the EMS provisions that external-feature name by reading the FIM/XML file.

Features Defined in FIM/XML and Shared iFC

The Shared iFC file defines the features invoked by Cisco BTS 10200. The FIM/XML defines the information pertaining to interactions between these features.

Table 7 explains the parameter names that can be configured in the FIM/XML and Shared iFC.

Provisioning iFC

To enable the operator to provision iFC (s) through the XML file, the service provider must generate and install the new XML file (Shared iFC file).

The XML file allows the operator to provision iFC (s) by allowing

•External feature definition

•Vertical Service Code (VSC) to feature mapping by defining a star-code if necessary for invoking an external Application Server-driven feature

•SIP trigger profile specifies which application server needs to be contacted and how to populate the Route-headers

•Sip Trigger Profiles (Subscriber Specific)

The XML file enables the operator to define the mapping of one sip_trigger_profile to multiple subscribers. The following commands list the CLI commands corresponding to entries in the Shared iFC file:

•Defining a New feature as the Originating Feature.

•Defining a VSC

Defining a New feature as the Originating Feature

This command defines the new feature as the originating feature.

add/change feature fname=ABC; tdp1=collected_information; tid1=ohd_trigger; ttype1=R; 
tdp2=o_exception; tid2=reroute_trigger; ttype2=R; tdp3=collected_information; 
tid3=vertical_service; ttype3=R; feature_server_id=FSPTC235;

Defining a VSC

This command defines a VSC which when dialed invokes the external feature.

add/change vsc digit-string=*72;fname=ABC;

Defining the SIP Trigger Profile

This command defines the SIP Trigger Profile used with the external feature.

add sip-trigger-profile id=vdial+noivr; 
route_guide_id=60001;AS_ROUTE_HEADER_USER=vdial+noivr;

Feature Configuration

This command defines the feature configuration.

add feature-config fname=ABC; type=DEFAULT-SIP-TRIGGER-PROFILE; value=AS_1;

Subscriber-Sip-Trigger-Profile

This command adds the Subscriber-Sip-Trigger-Profile.

add subscriber-sip-trigger-profile sub-id=sub_1; fname=ABC; sip-trigger-profile-id=AS_1;

Service-Id

This command adds the Service ID.

add service id=ohd_vsc; fname1=ABC; 

Subscriber-Service-Profile

This command adds the Subscriber-Service-Profile.

add service id=ohd_vsc; fname1=OHD; fname2=NEW; fname3;

Feature Restrictions and Limitations

The FIM/XML tool cannot be used to

•Change the interaction between internal features

•Define feature configuration properties

•Define feature support profile