Diameter Client Input

Introduction

The TIBCO StreamBase® Client Input Adapter for Diameter is used to receive Diameter messages from a connection and push those messages into EventFlow. The adapter will only output Diameter messages that this adapter is set up to produce. Multiple input adapters can be used on the same configuration to reduce the number of ports on each adapter, and help to organize the application. The application commands property on the property page is used to determine which messages from the Diameter dictionary are pushed into the application off the connection and into the EventFlow.

Adapter Properties

This section describes the properties you can set for this adapter, using the various tabs of the Properties view in StreamBase Studio.

General Tab

Name: Use this required field to specify or change the name of this instance of this component, which must be unique in the current EventFlow module. The name must contain only alphabetic characters, numbers, and underscores, and no hyphens or other special characters. The first character must be alphabetic or an underscore.

Adapter: A read-only field that shows the formal name of the adapter.

Start with application: If this field is set to Yes (default) or to a module parameter that evaluates to true, this instance of this adapter starts as part of the JVM engine that runs this EventFlow module. If this field is set to No or to a module parameter that evaluates to false, the adapter instance is loaded with the engine, but does not start until you send an sbadmin resume command, or until you start the component with StreamBase Manager.

Enable Error Output Port: Select this check box to add an Error Port to this component. In the EventFlow canvas, the Error Port shows as a red output port, always the last port for the component. See Using Error Ports to learn about Error Ports.

Description: Optionally enter text to briefly describe the component's purpose and function. In the EventFlow canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.

Operator Properties Tab

Property Type Description
Adapter Configuration Drop-down list The adapter configuration from the configuration file to use with this adapter.
Application Commands string[][] This is the list of Application and Command codes that this adapter instance will expose on its ports. The Application column is the name value from the dictionaries application section. The Command column is the name value of the command in the dictionary. Each row in this setting produces a port on the adapter with the generated schema, based on the dictionary for the command required.

Concurrency Tab

Use the Concurrency tab to specify parallel regions for this instance of this component, or multiplicity options, or both. The Concurrency tab settings are described in Concurrency Options, and dispatch styles are described in Dispatch Styles.

Caution

Concurrency settings are not suitable for every application, and using these settings requires a thorough analysis of your application. For details, see Execution Order and Concurrency, which includes important guidelines for using the concurrency options.

Diameter Input Ports

The schema for the input ports are partially static fields created by the adapter and partially dynamically created based on the dictionary provided. The following explains the fields that the adapter creates. Not all fields are required to be filled out to send a Diameter message. The required fields will vary depending on the message based on the dictionary file selected and its requirements. The field socketIdentifier and sendType must have a value of request or answer. If this is a request message then the requestMessage.header.applicationId and requestMessage.header.commandCode must be set, which determine the Diameter message type to send.

Field Name Field Type Description
socketIdentifier string This is a unique identifier for each client socket connection. This field is required for the output adapter when sending a Diameter message. The controller adapter will also output this value as the object field of a connection status message.
receiveType string This field will be one of two values: answer or request, and will be filled out by the adapter when a message is received from the Diameter connection. If the value is answer that means the Diameter message is an answer to a request that had been previously sent. If the value is request that means this is a request message. This value should be blank when starting a new request and sending a tuple into an output adapter. If this value is not blank it is ignored.
sendType string This field will be one of two values: answer or request. This value should be set by your EventFlow application to tell the output adapter how to handle sending this message. If the value is request the output adapter will use the requestMessage field as the value to send; if the value is answer the output adapter uses the answerMessage field as the value to send.
receivedTime timestamp This field is for information purposes only. It does not need to be set to send a message and is ignored.
receivedTimeNanoSeconds long This field is for information purposes only. It does not need to be set to send a message and is ignored.
latencyNanoSeconds long This field is for information purposes only. It does not need to be set to send a message and is ignored.
requestMessage tuple This field is dynamically created for each message type that this adapter is set up to handle. The messages schema is created by using the dictionary file provided. Although this message is dynamically created a standard Diameter header is also provided. If the sendType is set to request then the values in this tuple are used when creating the outbound Diameter message.
requestMessage.header.version int The version of the Diameter application. This value is automatically filled in when sending a message based on the adapter configuration.
requestMessage.header.length int The length of the Diameter message, this value is automatically filled in when sending a message.
requestMessage.header.request boolean This value is automatically filled in when sending a message.
requestMessage.header.proxiable boolean A Boolean flag which determines whether this message is proxiable.
requestMessage.header.error boolean This value is automatically filled in when sending a message.
requestMessage.header.retransmitted boolean A Boolean flag which determines if this message was retransmitted.
requestMessage.header.commandCode int The command code of this Diameter message. This value is required when sending a request message.
requestMessage.header.applicationId long The application ID of this Diameter message. This value is required when sending a request message.
requestMessage.header.hopByHop int This field is used to match the requests with their answers as the same value in the request is used in the response. This value is automatically filled in for you when sending a message.
requestMessage.header.endToEnd int This field is used to detect duplicate messages along with the combination of the Origin-Host AVP. This value is automatically filled in when sending a message.
answerMessage tuple This field is dynamically created for each message type that this adapter is set up to handle. The messages schema is created by using the dictionary file provided. Although this message is dynamically created, a standard Diameter header is also provided. If the sendType is set to answer then the values in this tuple are used when creating the outbound Diameter message.
answerMessage.header.version int The version of the Diameter application. This value is automatically filled in when sending a message based on the adapter configuration.
answerMessage.header.length int The length of the Diameter message. This value is automatically filled in when sending a message.
answerMessage.header.request boolean This value is automatically filled in when sending a message.
answerMessage.header.proxiable boolean A Boolean flag that determines if this message is proxiable.
answerMessage.header.error boolean This value is automatically filled in when sending a message.
answerMessage.header.retransmitted boolean A Boolean flag that determines if this message was retransmitted.
answerMessage.header.commandCode int The command code of this Diameter message, this value is required to send a request message.
answerMessage.header.applicationId long The application ID of this Diameter message. This value is required when sending a request message.
answerMessage.header.hopByHop int This field is used to match the requests with their answers as the same value in the request is used in the response. This value is automatically filled in when sending a message.
answerMessage.header.endToEnd int This field is used to detect duplicate messages along with the combination of the Origin-Host AVP. This value is automatically filled in when sending a message.

Message Handling

This section describes how messages are handled if they are not exposed to the EventFlow application, by specifying the application and command on one of the configured adapters.

Handled Messages

The following lists the Diameter message types that are handled internally if they are not exposed to the EventFlow application

  • CER - Capabilities-Exchange-Request

  • CEA - Capabilities-Exchange-Answer

  • DWR - Device-Watchdog-Request

  • DWA - Device-Watchdog-Answer

  • DPR - Disconnect-Peer-Request

  • DPA - Disconnect-Peer-Answer

Unhandled Messages

There are two types of unhandled messages: those that are part of the dictionary but not exposed to the EventFlow application, and those messages that are not in the provided dictionary files.

If a Diameter message is received but cannot be found in the dictionary file, then a status and log error message will be output with the error. The client is subsequently disconnected.

If a Diameter message is received and found in the dictionary but no adapter is set up to handle the message, an INFO warning is displayed in the logs that states the application and command code that was received and not handled.

Shared Adapter Configuration

This section describes the shared adapter configuration block found in the sbd.sbconf file.

Adapter Shared Location

The shared adapter configuration for the Diameter adapters is located in the sbd.sbconf file under the streambase-configuration and adapter-configurations XML elements.

Each shared adapter configuration must be under an element called adapter-configuration with a name attribute of DiameterAdapters. Following that, an element named section with a name attribute of DiameterAdapter is required.

Example Shared Adapter Configuration

<?xml version="1.0" encoding="UTF-8"?>
<streambase-configuration xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.streambase.com/schemas/sbconf/">
    <adapter-configurations>
        <adapter-configuration name="DiameterAdapters">
            <section name="DiameterAdapter">
                <setting name="id" val="DiameterSectionedMessagesServer"/>
                <setting name="dictionary" val="TestDictionary.json"/>
                <setting name="host" val=""/>
            </section>
            <section name="DiameterAdapter">
                <setting name="id" val="DiameterSectionedMessagesClient"/>
                <setting name="dictionary" val="TestDictionary.json"/>
                <setting name="host" val="127.0.0.1"/>
            </section>
            <section name="DiameterAdapter">
                <setting name="id" val="DiameterSectionedMessagesClient2"/>
                <setting name="dictionary" val="TestDictionary.json"/>
                <setting name="host" val="127.0.0.1"/>
            </section>
        </adapter-configuration>
    </adapter-configurations>
</streambase-configuration>

Shared Adapter Configuration Options

Property Type Default Description
id string   This is the name that will link the adapters together and is displayed in the drop down list on each adapters property configuration.
dictionary string   This is the filename of the Diameter dictionary file that will be for composing and parsing Diameter messages.
host string   For the server this is the host it will accept connections on, leave blank for all, and for the client this is the host to connect to.
port int 3868 For the server this is the port the server listens on; for the client, this is the port the client will create the outbound connection to.
networkProtocol string tcp Valid values are tcp and sctp and will determine the underlying network protocol to use.
startServerAtStartup boolean true Only valid for server adapters. If set to true, the server creates a listener at the startup of the application. If set to false, then the control port must be used to start the server listener.
connectAtStartup boolean true Only valid for client adapters. If set to true the client will attempt to connect to the server at startup of the application, if set to false then the control port must be used to establish a connection.
noDelay boolean false If set to true, the connection option no delay is set on the sockets.
maxDeviceWatchDogRequests int 3 The maximum number of device watch dog request messages to send before disconnecting.
watchDogTimeoutMS int 3000 The amount of time before the watch dog times out,in milliseconds, and sends a watchdog request.
originHost string 127.0.0.1 The origin host to use with the connection.
originRealm string my.realm The origin realm to use with the connection.
productName string StreamBase The product name to use with the connection.
firmwareVersion int 210 The firmware to use with the connection.
readBufferSize int 102400 The number of bytes for each sockets circular read buffer.
writeBufferSize int 102400 The number of bytes for each sockets circular write buffer.

Diameter Dictionary

This section describes Diameter dictionaries and how they are used with the adapters to parse and compose Diameter messages.

Dictionary files are in JSON format and are cumulative in that you can include more dictionary files inside of other dictionary files to keep them organized and less complex.

Base Dictionary

The Diameter sample that comes with StreamBase includes a BaseDictionary.json file which should be the base for all of your projects. This base dictionary includes all the required information for the Diameter adapters to perform the most basic Diameter protocol functions. The sample also includes a TestDictionary.json that shows the most basic dictionary files, including the base dictionary, to get the adapters up and running.

Dictionary Schema

The following shows the schema to which each dictionary must conform:

{
   "$schema":"http://json-schema.org/draft-04/schema#",
   "type":"object",
   "properties":{
      "includeDictionary":{
        "type":"array",
         "items":{
            "type":"object",
            "properties":{
               "file":{
                  "type":"string"
               }
            },
            "required":[
               "file"
            ]
         }       
      },
      "settings":{
        "type":"object",
        "properties":{
           "enumAsString":{
              "type":"boolean"
           },
           "applicationAndCommandAsString":{
              "type":"boolean"
           }
        }        
      },
      "vendors":{
         "type":"array",
         "items":{
            "type":"object",
            "properties":{
               "name":{
                  "type":"string"
               },
               "id":{
                  "type":"string"
               },
               "code":{
                  "type":"integer"
               }
            },
            "required":[
               "name",
               "id",
               "code"
            ]
         }
      },
      "dataTypes":{
         "type":"array",
         "items":{
            "type":"object",
            "properties":{
               "dataType":{
                  "type":"string"
               },
               "parentDataType":{
                  "type":"string"
               }
            },
            "required":[
               "dataType"
            ]
         }
      },
      "avps":{
         "type":"array",
         "items":{
            "type":"object",
            "properties":{
               "name":{
                  "type":"string"
               },
               "code":{
                  "type":"integer"
               },
               "vendorId":{
                  "type":"string"
               },
               "must":{
                  "type":"array",
                  "items":{
                     "enum":[
                        "M",
                        "V",
                        null
                     ]
                  }
               },
               "must-not":{
                  "type":"array",
                  "items":{
                     "enum":[
                        "M",
                        "V",
                        null
                     ]
                  }
               },
               "type":{
                  "type":"object",
                  "properties":{
                     "dataType":{
                        "type":"string"
                     },
                     "enum":{
                        "type":[
                           "array",
                           "object"
                        ],
                        "items":{
                           "type":"object",
                           "properties":{
                              "value":{
                                 "type":"integer"
                              },
                              "name":{
                                 "type":"string"
                              }
                           },
                           "required":[
                              "name"
                           ]
                        }
                     }
                  },
                  "required":[
                     "dataType"
                  ]
               },
               "grouped":{
                  "type":"array",
                  "items":{
                     "type":"object",
                     "properties":{
                        "name":{
                           "type":"string"
                        },
                        "min":{
                           "type":"integer"
                        },
                        "max":{
                           "type":"integer"
                        }
                     }
                  }
               }
            },
            "required":[
               "name",
               "code"
            ]
         }
      },
      "applications":{
         "type":"array",
         "items":{
            "type":"object",
            "properties":{
               "applicationId":{
                  "type":"integer"
               },
               "name":{
                  "type":"string"
               },
               "commands":{
                  "type":"array",
                  "items":{
                     "type":"object",
                     "properties":{
                        "name":{
                           "type":"string"
                        },
                        "code":{
                           "type":"integer"
                        },
                        "proxiable": {
                            "type":"boolean"
                        },
                        "request":{
                           "type":"array",
                           "items":{
                              "type":"object",
                              "properties":{
                                 "name":{
                                    "type":"string"
                                 },
                                 "min":{
                                    "type":"integer"
                                 },
                                 "max":{
                                    "type":"integer"
                                 },
                                 "vendorId":{
                                    "type":"string"
                                 },
                                 "index":{
                                    "type":"integer"
                                 },
                                 "hidden":{
                                    "type":"boolean"
                                 }
                              },
                              "required":[
                                 "name",
                                 "min"
                              ]
                           }
                        },
                        "answer":{
                           "type":"array",
                           "items":{
                              "type":"object",
                              "properties":{
                                 "name":{
                                    "type":"string"
                                 },
                                 "min":{
                                    "type":"integer"
                                 },
                                 "max":{
                                    "type":"integer"
                                 },
                                 "vendorId":{
                                    "type":"string"
                                 },
                                 "index":{
                                    "type":"integer"
                                 },
                                 "hidden":{
                                    "type":"boolean"
                                 }
                              },
                              "required":[
                                 "name",
                                 "min"
                              ]
                           }
                        }
                     },
                     "required":[
                        "name",
                        "code",
                        "proxiable",
                        "request",
                        "answer"
                     ]
                  }
               }
            },
            "required":[
               "commands",
               "applicationId"
            ]
         }
      }
   },
   "required":[
      "vendors",
      "dataTypes",
      "avps",
      "applications"
   ]
}
        

Dictionary Layout

The following are the major categories of the dictionary file and an overview of their usage.

includeDictionary

The includeDictionary section is an array of files that allows one dictionary file to include another dictionary file. This enables you to organize your dictionaries into logical application or vendor groups and combine them into a single dictionary.

  • file — The relative path to the linked dictionary file to include.

settings

The settings section allows dictionary related settings to be set.

  • enumAsString — The enumAsString setting is a true/false flag that determines if the string values of the enumerations in the dictionary should be used in EventFlow instead of the integer values. If set to true, the schemas produced by parsing the dictionary files will input/output a string value for all enum fields and require that any input fields match one of the enum values listed.

  • applicationAndCommandAsString — The applicationAndCommandAsString setting is a true/false flag that determines if the applicationId and commandCode fields of the request and answer message headers should be treated as string or numeric fields. If this value is true, the input and outputs of the adapters will consider the applicationId and commandCode to be string fields and match them to the dictionary name values. All messages read from the Diameter connection are translated to the correct string values, and all tuples are converted to the correct numeric values for the outbound Diameter messages.

vendors

The vendors section allows you to add vendor names and codes that will be used later in avp's and application commands.

  • name — The human-readable name of the vendor.

  • code — The code of the vendor to use with vendorId fields in other sections, for linking.

  • id — The ID of the vendor to send with Diameter messages.

dataTypes

The dataTypes section allows you to add any extended data types that are not already specified by the base dictionary.

  • dataType - The name of the data type which will be used when creating AVPs.

  • parentDataType - The parent data type which must eventually link back to one of the base underlying data types (OctetString, Integer32, Integer64, Unsigned32, Unsigned64, Float32, Float64).

avps

The avps (attribute value pairs) section allows you to add any AVPs that are not currently present in the base dictionary. These AVPs can be self-referenced to form nested structures. The AVPs are used in the application commands as the fields for each request and answer command.

  • name — The AVP name that is used later in the application commands to link AVPs to commands.

    code — The AVP code that is sent and used in the Diameter message.

    vendorId — (Optional) The vendor associated with this AVP, use the code of on of the vendors in the vendor section.

    must — An array of Diameter values to specify how this AVP will operate, value available:

    • M — In the must case it means the AVP must appear in the Diameter message or the message will be rejected.

    • V — In the must case it means the vendorId must have a value.

    must-not — An array of Diameter values to specify how this AVP will operate, value available:

    • M — In the must not case it means the AVP must NOT appear in the Diameter message or the message will be rejected.

    • V — In the must not case it means the vendorId must NOT appear in the Diameter message or the message will be rejected.

    type — The data type of this AVP which must correspond to one of the base or extended data types. If this field is missing then the grouped field must exist.

    grouped — An array of nested AVP values.

    • name — The name of the AVP to include.

    • min — (Optional) The minimum number of times this value must appear.

    • max — (Optional) The maximum number of times this value must appear.

applications

The applications section allows you to add any applications and commands that are not currently present in the base dictionary. The applications section is the main building block for creating a Diameter application and is comprised of multiple commands. Each command in turn has a request and answer message that is created from one or many AVPs listed in the AVP section.

  • applicationId — The application ID used when sending Diameter messages, this value is also used during the capabilities exchange.

  • name — The human-readable name of this application to use in the adapter properties.

  • commands — The array of commands associated with this application.

    • name — The name of the command and is used in the adapter properties.

    • code — The code of the command used to create the Diameter message.

    • proxiable — A flag to specify if this command is proxiable.

    • request/answer — An array of AVP values which make up the request/answer commands.

      • name — The name of the AVP to include.

      • min — (Optional) The minimum number of times this value must appear.

      • max — (Optional) The maximum number of times this value must appear.

      • vendorId — (Optional) The vendor associated with this AVP; use the code of one of the vendors in the vendor section.

      • index — (Optional) The index of this AVP value is the order of the AVP values.

      • hidden — (Optional) If hidden is true, the AVP value will be parsed from messages but is ignored in the StreamBase application and does not appear in the generated schema. This value cannot be true if the min value present and is greater than 0.