Home
MATRIXX 5G Integration
MATRIXX SBA Gateway
This section describes the Service Based Architecture (SBA) Gateway, which provides the framework to build 5G network function (NF) services based on 3GPP technical specifications.
Configuring SBA Gateway
SBA Gateway is configured as 5G network functions in several ways.
Mapping JSON Messages to MDCs
SBA Gateway uses OpenAPI (Swagger) specifications to check the format of incoming JSON requests. After validation, these JSON messages are mapped to _glossary/mdc.html structures using the Dynamic Message Mapper. This uses Mapping configuration files to map fields in the incoming JSON request to and from MDCs before sending them to and from MATRIXX Engine.
Providing Your Own Mapping Configuration
You can use partial mapping files to override only the mapping configuration defaults you want to change.

Welcome
MATRIXX Release Notes
MATRIXX Architecture
MATRIXX Installation and Upgrade
MATRIXX Configuration
MATRIXX Security
MATRIXX Integration
MATRIXX Diameter Integration
MATRIXX Call Control Framework Integration
MATRIXX TM Forum Integration
MATRIXX 5G Integration
- About MATRIXX 5G Integration
  MATRIXX 5G Integration describes how to implement the Service-Based Architecture (SBA) Gateway and messaging. In addition, this document provides information about security configuration (secured and not secured).
- MATRIXX SBA Gateway
  This section describes the Service Based Architecture (SBA) Gateway, which provides the framework to build 5G network function (NF) services based on 3GPP technical specifications.
  - MATRIXX SBA Gateway Overview
    SBA Gateway converts incoming 5G JSON messages to MATRIXX Data Containers (MDCs) and forwards these requests to the Traffic Routing Agent (TRA), which routes them to the correct sub-domain on MATRIXX Engine. Outgoing messages are converted from MDCs to 5G JSON messages.
  - Installing SBA Gateway
    This section describes installing SBA Gateway in hybrid deployments and installing CHF within an Istio service mesh.
  - Upgrading SBA Gateway
    When upgrading to a new version of SBA Gateway, there are several things you must consider to ensure the upgrade is successful and the correct configuration is applied.
  - Viewing the SBA Gateway Version
    You can use version, revision, and timestamp data to check which version of SBA Gateway is running.
  - Configuring SBA Gateway
    SBA Gateway is configured as 5G network functions in several ways.
    - Creating a CHF Configuration Source
      The Charging Function (CHF) configuration source template has files that can be used to create an image for configuring the CHF network function as a docker type configuration source.
    - Defining the Common SBA Gateway Configuration
      The common SBA Gateway configuration, provided by the SBA library, defines a default configuration that is shared by every network function.
    - Configuring SBA Gateway Properties
      SBA Gateway network functions are configured using environment variables or by editing the configuration in the nf.yaml file for the network function.
    - Configuring CHF
      The CHF configuration overrides some properties defined in gateway.yaml but only for this particular network function (CHF).
    - Configure an SBA Gateway HTTP/2 Connection to Traffic Routing Agent
      Configure an HTTP/2 connection with Traffic Routing Agent (TRA-RT/DR) using the SBA Gateway sub-chart of the main MATRIXX Helm chart.
    - MDC Handlers
      CHF configuration supports the definition of MATRIXX Data Container (MDC) handlers that process the messages received by one or more network function endpoints. These handlers convert JSON messages to MDCs before sending them to MATRIXX Engine. The response is converted from MDC format back to JSON and returned to the endpoint.
    - Configuring Multiple Sub-Domains
      In an environment with multiple sub-domains, incoming traffic is directed to the correct sub-domain by the Traffic Routing Agent (TRA) positioned in the topology between the SBA Gateway (CHF) and MATRIXX Engine.
    - Mapping JSON Messages to MDCs
      SBA Gateway uses OpenAPI (Swagger) specifications to check the format of incoming JSON requests. After validation, these JSON messages are mapped to _glossary/mdc.html structures using the Dynamic Message Mapper. This uses Mapping configuration files to map fields in the incoming JSON request to and from MDCs before sending them to and from MATRIXX Engine.
      - Providing Your Own Mapping Configuration
        You can use partial mapping files to override only the mapping configuration defaults you want to change.
      - Mapping Custom MDCs
        A common use case for mapping a custom _glossary/mdc.html is to extend the Mtx5GMsg MDC and some MDCs within it, for example, Mtx5GMultiUnitUsageData. A subtype notation which involves adding the type name of a field after the field name, separated by an exclamation mark enables this kind of mapping.
    - Routing SBA 5G Requests
      The TRA-RT requires that any MATRIXX Data Containers (MDCs) submitted have sub-domain routing information provided in the MtxMsg.TrafficRouteData field.
    - Network Function Endpoints
      Network function endpoints define the URLs and HTTP methods that they accept. Optionally, they can also check HTTP headers, path variables, or query parameters.
    - NRF Client Load and Capacity Reporting
      The NRF Client can report load and capacity values to the NRF.
    - Overriding nfProfile Fields
      A common requirement is having a common nfProfile for all environments where a few values can be overridden for each environment. This can be achieved using the global variables section of the common configuration.
    - Backstop Processing
      Backstop Processing is functionality that returns a positive message when downstream components are not available.
    - Rating Bypass
      You can configure business logic in the SBA Gateway Charging Function (CHF) to filter charging requests and spending limit requests that should not be sent to the Charging Server for rating.
    - Response Generator
      Response Generator is functionality used by Backstop Processing and Rating Bypass functionality to generate a custom response.
    - Spending Limit Notification Error Processing
      When MATRIXX Engine receives an unsuccessful Mtx5GSpendingLimitResponse, the session is retained or ended based on a configuration table in mtx_config.xml.
    - ActiveMQ Gateway Configuration
      MATRIXX Engine uses ActiveMQ to produce outbound 5G Notify requests for SBA Gateway and to consume their inbound responses.
    - Customize 5G Messages
      In MATRIXX, you can extend the 5G request and response messages beyond the options specified in the 3GPP specification.
  - Monitoring and Logging
    You administer the SBA Gateway by configuring its logging and monitoring features. For more information about monitoring SBA Gateway administration tasks, see the discussions about monitoring SBA Gateway and configuring the SNMP Prometheus adapter in MATRIXX Monitoring and Logging.
  - Creating a Mapping Configuration
    The following documentation provides information about how to create a mapping configuration. For a list of 5G message mappings from MATRIXX Data Container (MDCs) to OpenAPI supported by MATRIXX, see the discussion about MATRIXX 5G message mapping.
  - Security
    SBA Gateway supports HTTP BASIC authentication and TLS Mutual Authentication.
  - API for 5G Integration
    The URI, mapping, and OpenAPI specification are configurable, and only the HTTP method and mapping filename are not.
  - Throttling
    SBA Gateway can be throttled to protect the platform from overload conditions.
  - Connecting to Multiple Networks with Multus
    Depending on requirements, SBA Gateway might require a dedicated connection to the 5G network separate from its connection to other MATRIXX components.
  - MATRIXX 5G Message Mapping
    The following sections describe the default configuration for SBA Gateway-supported 5G message mapping. Topics in the following sections describe the mappings from MATRIXX Data Container (MDC) format to OpenAPI format for each 3GPP 5G version.
- Charging Function
  This section describes the Charging Function components and how to deploy and configure them.
MATRIXX 5G Event Streaming
MATRIXX Event Streaming
MATRIXX Administration
MATRIXX Web App Administration
MATRIXX Monitoring and Logging
MATRIXX Policy
MATRIXX Kafka CDR Consumer
MATRIXX Pricing and Rating
MATRIXX Pay Now
MATRIXX Subscriber Management
MATRIXX Subscriber Management API
MATRIXX Business API SDK
My MATRIXX Help
MATRIXX Backoffice Customer Tool Help
MATRIXX Third-Party Licenses
Glossary

Providing Your Own Mapping Configuration

You can use partial mapping files to override only the mapping configuration defaults you want to change.

Default mapping files are located in the /opt/mtx/conf/mapping/3GPP_schema_version/base. A stub mapping file referencing the default file is located in /opt/mtx/conf/mapping/3GPP_schema_version. The contents of the stub file are similar to the following:

baseFile: ${current.directory}/base/ChargingDataRequest-5230-mapping.yaml

Where the value of ${current.directory} is replaced by the location of the file when it is loaded.

Add your changes to the stub file after the baseFile link to override the matching properties in the defaults. For example to add your own output parameter that adds an HTTP header to the response, add the following in /opt/mtx/conf/R15-2019-12/ChargingDataResponse-5230-mapping.yaml:

baseFile: ${current.directory}/base/ChargingDataResponse-5230-mapping.yaml
 
outputParameters:
  http-response-header-CustomHeader: {from: "#params.custom-input-parameter", default: "not set"}

This adds the output parameter entry to the existing mapping by merging the two files. If the default mapping configuration file is changed to fix an issue or support new functionality, those changes are adopted without you having to rebase your custom mapping configuration file.

Note: A limitation of the merge functionality is that it does not work with lists. Lists are entirely overwritten. If your change makes a change to a structure that includes a list, you must resupply the whole list to avoid loss of configuration data.