Create a Custom MDC

You create a custom MATRIXX Data Container (MDC) to capture additional data that is used during rating or post-processing operations, such as adding fields to extend the system MtxDiamRoMsg MDC or to a MATRIXX Event File (MEF). The custom MDC can be an extension of a system MDC, an existing custom MDC, or not be based on any MDC.

About this task

This task assumes you are changing a MATRIXX Engine installation that is online, in production, and has multiple engines. In such cases, you must perform this procedure on an engine running in standby mode. If you are changing an offline engine, you need not perform any steps after running the configure_engine.py script, except to run the script again on the other engines. If you are changing a single engine, you need not perform any steps after running the configure_engine.py script.

Procedure

  1. Use a configuration source to configure the grouped AVP in create_config.info. You must delete the following create_config.info question: 
    Do you want to add any private MDCs?

    The MATRIXX Engine configuration source can configure multiple configuration files to be merged at start-up as inputs for the create_config.py command. Files are loaded in alphabetical order. Each filename must end in create_config.info.

    For more information about configuration using a configuration source, see the discussion about configuration sources in MATRIXX Configuration.
  2. Run create_config.py.
    For example:
    kubectl exec -it engine_pod_name -n matrixx -- bash --login -c"create_config.py"
  3. When you are prompted to add any private MDCs, answer y and provide the following information:
    • The MDC name.
      MATRIXX data container names start with Mtx. Do not use this prefix for custom MDCs. MATRIXX suggests using a prefix that identifies MDCs uniquely for the data segment or service provider.
      Note: MDC names cannot include dashes (-).
    • The MDC key.

      MATRIXX identifies and locates MDCs by their key value during processing. To ensure there are no conflicts between MATRIXX data containers and customer-defined data containers, use a unique negative integer for each custom data container to add. For best performance, start with -1 and decrement sequentially for each new MDC. Once a value has been assigned, you cannot reuse it or change it.

    • The base data container for the MDC.

      If the custom data container is an extension of an existing MDC, system or custom, specify the MDC on which it is based. The base data container is typically a top-level container. For example, a custom subscriber type uses the MtxSubscriberObject MDC as its base container. A custom device can use the MtxMobileDeviceObject or the MtxMobileLoginObject, each which extends the MtxDeviceObject MDC, as its base container. You cannot extend the MtxDeviceObject.

      To print to file a list of system MDC names: kubectl exec -it engine_pod_name -n matrixx -- bash --login -c"print_data_container_pickled_file.py" -s > system_mdc_list.txt

      For more information about print_data_container_pickled_file.py, see the discussion about print_data_container_pickled_file.py.

      If the base container is an MDC used in the diameter_dictionary_base.xml file, answer n to the question Diameter: Do you want to use the default Diameter Gateway dictionary (y/n)? to use the new MDC. In most situations when adding a field to this type of MDC, you also map the field to a Diameter AVP. However, you can also set the new field using a selective update.

      If the custom MDC is not an extension of an existing MDC, leave this question blank.

    • The created schema version. If this is a new MDC, enter a positive integer to identify the customer version of the MDC.
    • The deleted schema version. Enter 0.
    • The number of fields to add to the custom MDC.

      For each field to add, you must provide the field name and field data type and confirm whether it is a list or an array. For string and blob data types, you can specify a maximum size of the field to save space. For more information, see the discussion about MATRIXX Engine Data Types.

      Note: If the field is for an IPv4 address, use the unsigned int32 data type for the field. If the field is for an IPv6 address, use the unsigned int128 data type.

What to do next

When create_config.py finishes, update the configuration on each server in the engine as described in the discussion about configuring MATRIXX Engine.

In addition, update the REST API bindings with the MDC changes. For more information, see the discussion about updating the MDC definitions for RS Gateway.