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:

deploy-sentinel-sip/config/sentinel-diameter-ra-deploy/profiles/DiameterExtension-AVP.yaml
deploy-sentinel-sip/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: 1
    ProtectedRule: 1
    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 Express includes the module pack sentinel-sip-avp-cdr-feature that can be used to write your own CDR feature.

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 4.1.0 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/4.1;4.1.0:

Run the command:

create-module acme-sip-avp-feature opencloud#sentinel-sip-avp-cdr-feature#sentinel-sip/4.1;4.1.0

This command:

  • downloads the module pack from the repository

  • creates a new directory called acme-sip-avp-feature inside your Sentinel Express 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 my-sip-avp-feature com.opencloud.rhino.sentinel-sip#sentinel-sip-avp-cdr-feature;4.1.0
Extracting '/home/testuser/sentinel-express-sdk/repositories/opencloud-offline-mirror/com.opencloud.rhino.sentinel-sip/sentinel-sip-avp-cdr-feature/4.1.0/sentinel-sip-avp-cdr-feature-module-pack-4.1.0.zip' to '/home/testuser/sentinel-express-sdk/my-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 [my-sip-avp-feature]: acme-sip-avp-feature 1

The longest common package prefix is 'com.opencloud.sentinel.feature.common.cdr.session'.
Rename package prefix 'com.opencloud.sentinel.feature.common.cdr.session' to [com.opencloud.sentinel.feature.common.cdr.session]: 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
New package prefix is the same as old prefix. Java package declarations will not be re-namespaced.

Renaming ivy modules and updating dependencies.

Renaming symbolic property references in source files.

Commenting out OID mappings in source files. These should be uncommented and
replaced with the appropriate OID mapping for the new module.
Checking "deps.properties" for missing values.

Done. New module(s) should now be available at: /home/testuser/sentinel-express-sdk/my-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 on the PostEndSession execution point, so simply replacing run SipAvpCdr with run AcmeSipAvpCdr in deploy-sentinel-sip/config/sentinel-sip-full-deploy/profiles/PlatformOperatorName_FeatureExecutionScriptTable.yaml at that execution point will be enough to enable the new feature.

Extending Interim CDRs generated by Sentinel

Interim CDRs are written at various points during a session.

Module Pack for Interim CDRs

Sentinel Express includes the module pack sentinel-sip-interim-cdr that can be used to write your own interim CDR feature.

Create your own module from the module pack, using the create-module command. When creating your own module from the module pack use a new feature name, and provide a different Java namespace than the default feature - this enables co-existence of your new feature and the existing "out of the box" feature.

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

Updating feature execution scripts for Interim CDRs

The "out of the box" feature name is SipInterimCdr. So replacing run SipInterimCdr with run MyFeatureName in deploy-sentinel-sip/config/sentinel-sip-full-deploy/profiles/PlatformOperatorName_FeatureExecutionScriptTable.yaml at all execution points will be enable the new feature.

The feature is run in the following execution points:

  1. System post for SipAccess CreditAllocatedPostCC

  2. System post for SipAccess CreditLimitReachedPostCC

  3. System post for SipAccess ControlNotRequiredPostCC

  4. System pre for SipAccess OCSFailurePostCC

  5. System post for SipAccess PartyRequest

  6. System post for SipAccess ServiceTimer

  7. System post for SipMidSession CreditAllocatedPostCC

  8. System post for SipMidSession CreditLimitReachedPostCC

  9. System pre for SipMidSession OCSFailurePostCC

  10. System post for SipMidSession PartyRequest

  11. System post for SipMidSession PartyResponse

  12. System post for SipEndSession

  13. System post for SubscriptionSubscriberCheck

  14. System post for SubscriptionSipRequest

  15. System post for SubscriptionSipResponse

  16. System post for SipTransaction SubscriberCheck

  17. System post for SipTransaction Request

  18. System post for SipTransaction Response

  19. System post for SipLegEnd

If you want to modify the feature execution points that the new CDR feature should run at you may also have to orverride the generateInterimCdrTriggers() method. This method checks the current feature execution point at feature runtime and based on that generates the list of InterimCDRTrigger objects that get passed to the createCdr() method.

Previous page Next page