Defining extension AVPs

In order for Rhino to be able to handle extension AVPs they need to be defined in two Diameter-specific profile tables, DiameterExtension-AVP and DiameterExtensions. The source for these profile tables are the two respective YAML files in the sentinel-diameter-ra-deploy module. The paths to the profile tables relative to the SDK root directory are:

ipsmgw-deploy/config/sentinel-diameter-ra-deploy/profiles/DiameterExtension-AVP.yaml
ipsmgw-deploy/config/sentinel-diameter-ra-deploy/profiles/DiameterExtensions.yaml

The DiameterExtension-AVP profile table contains one profile for every extension AVP. Below is an example of such an AVP definition:

OC-Sentinel-Selection-Key:
    AvpCode: 1001
    AvpName: OC-Sentinel-Selection-Key
    AvpType: UTF8String
    MandatoryRule: 0
    ProtectedRule: 0
    VendorId: 19808

See Configuring Extension AVPs for the full documentation of these profile tables.

Extending CDRs generated by Sentinel

Sentinel defines the general format of the CDRs as a collection of arbitrary AVPs, and specialised features are then used to create AVPs from session state information and write the AVPs to a CDR. Therefore there should be no need to modify the protocol buffers definition (i.e. disk format does not need modification). However, if custom information should be written to CDRs using extension AVPs then these need to be defined in the Diameter profile configuration files in the deployment module.

Sentinel provides to enable extension of both Session CDRs and Interim CDRs.

Extending Session CDRs generated by Sentinel

A Session CDR means a CDR that is written once per Session.

AVP CDR feature module pack

Sentinel IP-SM-GW includes two module packs for writing CDR features: sentinel-sip-avp-cdr-feature and ipsmgw-avp-cdr-feature. The former contains most of the code for populating CDRs, the latter extends that feature and adds a few IP-SM-GW-specific fields. Since you may need to modify certain methods in the base feature it is recommended that you create features from both module packs as explained below and then only work on the IP-SM-GW feature, copying code from the base feature as needed.

Note that if you want to completely replace the CDR generation then you will have to change the feature class signature so as not to inherit from the base feature by changing the line

public class AcmeSipAvpCdrFeature extends BaseSipAvpCdrFeature {

to

public class AcmeSipAvpCdrFeature extends BaseFeature<SentinelSipSessionState, SentinelSipMultiLegFeatureEndpoint>
    implements SipFeature, InjectResourceAdaptorProvider, InjectFeatureStats<CDRStats> {

and copy over all the necessary methods.

Creating a Module from the Module Pack

For background information refer to Module Packs and Creating a Feature for general information on how to create, build and deploy a new feature.

Note The examples given assume the SDK was installed for (vendor=Acme Inc, vendorKey=acme, version=1.5)

To view the available module-packs, type the following command inside the sdkadm tool:

list-modules +module-pack
Note Where you see a version number of 2.4.0.2 use the version number of the product you have downloaded.

Now create a new module from the module pack published in opencloud#sentinel-sip-avp-cdr-feature#sentinel-sip/2.4.0;2.4.0.2:

Run the command:

create-module acme-sip-avp-feature opencloud#sentinel-sip-avp-cdr-feature#sentinel-sip/2.4.0;2.4.0.2

This command:

  • downloads the module pack from the repository

  • creates a new directory called acme-sip-avp-feature inside your Sentinel IP-SM-GW SDK, which contains all the newly created modules

  • scans the content of the module pack and prompts you to enter new values where necessary

  • re-writes the new modules according to your answers.

When prompted, answer as shown in the example output below. Numbered annotations mark the prompts, and their answers are listed by number immediately after the example output.

> create-module acme-sip-avp-feature opencloud#sentinel-sip-avp-cdr-feature#sentinel-sip/2.4.0;2.4.0.2
downloading https://repo.opencloud.com/artifactory/opencloud-internal-snapshots/opencloud/sentinel-sip/2.4.0/sentinel-sip-avp-cdr-feature/2.4.0.2/sentinel-sip-avp-cdr-feature-module-pack-2.4.0.2.zip ...
... (12kB)
.. (0kB)
        [SUCCESSFUL ] opencloud#sentinel-sip-avp-cdr-feature#sentinel-sip/2.4.0;2.4.0.2!sentinel-sip-avp-cdr-feature-module-pack.zip(module-pack) (81ms)
Extracting '/home/testuser/ipsmgw-sdk/build/target/ivy-caches/online-resolvers.cache/opencloud/sentinel-sip-avp-cdr-feature/sentinel-sip/2.4.0/module-packs/sentinel-sip-avp-cdr-feature-module-pack-2.4.0.2.zip' to '/home/testuser/ipsmgw-sdk/acme-sip-avp-feature'.


Command line invocation did not contain enough rename arguments to rename all modules.
To specify rename arguments on the command line, include <oldvalue>:<newvalue> pairs as additional arguments.
Missing values will now be prompted for interactively.

Please enter a name for the top level module, usually this will match the name of the directory for the new module
Rename top level module 'sentinel-sip-avp-cdr-feature' to [acme-sip-avp-feature]: 1

The longest common package prefix is 'com.opencloud.sentinel.feature.common.cdr'.
Rename package prefix 'com.opencloud.sentinel.feature.common.cdr' to [com.opencloud.sentinel.feature.common.cdr]: com.acme.sentinel 2

Command line invocation did not contain enough rename arguments to rename all features.
To specify rename arguments on the command line, include <oldvalue>:<newvalue> pairs as additional arguments.
Missing values will now be prompted for interactively.

Rename feature 'SipAvpCdr' to [SipAvpCdr]: AcmeSipAvpCdr 3
Re-writing source files with new package declarations.

Renaming ivy modules and updating dependencies.

Renaming symbolic property references in source files.
Checking "deps.properties" for missing values.

Done. New module(s) should now be available at: /home/testuser/ipsmgw-sdk/acme-sip-avp-feature
1 Press Enter to accept the default
2 Type com.acme.sentinel and press Enter
3 Type AcmeSipAvpCdr and press Enter
Note It is possible to use the command in a non-interactive mode by providing all substitution values.
Run help create-module for instructions.

Modifying the Session CDR feature

The CDR feature module contains two classes: SipAvpCdrFeature and BaseSipAvpCdrFeature. BaseSipAvpCdrFeature contains the actual code, and SipAvpCdrFeature inherits from it and contains the feature annotations. This split is necessary to make it possible for other features to inherit the functionality of the base feature without causing problems with conflicting annotations.

When modifying the CDR feature you can choose to completely replace the existing code in the createCdr() method or to extend it with your own additions. Regardless of which you prefer, there are two main helper methods that make adding new AVPs to a CDR very easy:

addAvp()

This method simply takes a DiameterAvp object created through the Diameter API, in addition to the AvpCdrFormat.AvpCdr.Builder and DiameterMessageFactory instances created at the beginning of the createCdr() method, and adds it to the top level of the CDR. This is useful for standard AVPs. The feature contains two examples of how to use this method, the Subscription-Id AVP and the Service-Context-Id AVP.

addCustomAvp()

This method is used for adding extension AVPs to the top level of the CDR. In addition to the builder and message-factory arguments mentioned above it takes an AVP code, name, and value to create the AVP with. There are several examples in the feature that demonstrate how to use this method.

Warning By default the extension AVPs will be added with the OpenCloud vendor ID, so make sure to adjust the code to your needs in both the createCustomAvp() and createCdrAvp() methods when defining your own extension AVPs.
Note You may have to modify the createCustomAvp() method if the AVP you want to create is of a type that is not yet supported by that method.

Updating feature scripts for the Session CDR feature

In order for the new CDR feature to be used instead of the default one, the feature execution scripts have to be updated, replacing calls to the default feature with calls to the new one.

The feature is only run at the end of a session, which is made up of the default_sf_Post_SipEndSession and MOFSM_sf_Post_SipEndSession execution points, so simply replacing run IpsmgwAvpCdr with run AcmeSipAvpCdr in ipsmgw-deploy/config/ipsmgw-full-deploy/ipsmgw-service/profiles/PlatformOperatorName_FeatureExecutionScriptTable.yaml at these execution points will be enough to enable the new feature.

Previous page Next page