☰
Navigation :

Mapping File & Rules

Introduction

When the RTP application is configured to use file based rather than database configuration, the configuration is stored in a JSON mapping file which will contain a single RFC 8259 syntax JSON Object.

This file must be named mapping.json and must exist in the directory whose location is configured in the audio_dir configuration option for the RTP application. All other file paths are relative to that directory.

Here is a simple example containing two announcement definitions:

{
   "1" : {
      "description" : "Example menu prompt.\r\n",
      "play_list" : {
         "Arabic" : [
            {
               "file" : "Menu_Prompt",
               "type" : "file"
            }
         ],
         "English_AE" : [
            {
               "file" : "Menu_Prompt",
               "type" : "file"
            }
         ]
      }
   },
   "2" : {
      "description" : "en- You entered <Some Variable.>",
      "play_list" : {
         "Arabic" : [
            {
               "file" : "You_Entered",
               "type" : "file"
            },
            {
               "noun_gender" : "masculine",
               "skip_zero" : 0,
               "type" : "variable-integer"
            }
         ],
         "English_AE" : [
            {
               "file" : "You_Entered",
               "type" : "file"
            },
            {
               "type" : "variable-integer"
            }
         ]
      }
   }
}

Announcement ID

The top level element is an Object.

The keys of this Object are a String which represents a numeric Announcement ID.

The values of this Object are an Announcement Object as subsequently defined.

The Announcement ID must be an integer value in the range 0 - 2147483647.

A multi-audio announcement is the concatenation of a list of individual files within an announcement ID definition.

Announcement Object

Each Announcement Object has the following keys:

Play List Object

Each Play List is an Object.

The keys of this Object are the Language Names.

The values of this Object is an Array of Fragment Objects

Language Name String

When constructing the audio stream for an interaction the audio engine will always do this in the context of a single Language Name. If the service logic does not provide a Language Name a default Language Name is chosen based on RTPApp configuration.

The same Language Name is used for all Announcement ID mappings and also in the construction of all relevant variable parts. If variable parts are used, then the Language Name must exactly match the language name key for the variable parts codec

Fragment Objects

Each Fragment Object has the following keys:

The other keys depend on the type of the Fragment, as described below.

(file) Fragment Object

When type = file the following keys apply:

The full on-disk path for the audio file will be:

<audio_dir>/<language_name>/<fragment_file_without_suffix>.<suffix>

The relative file configured in file is expected to have a file suffix. This is typically .ul to indicate µ-Law encoding, which is the default, always-supported audio codec.

However, the system may be configured to support arbitrary additional audio codecs. Hence, this suffix will always be stripped, and replaced with the appropriate suffix for the actually-negotiated codec (which may of course be µ-Law and the .ul suffix).

NOTE: When configuring the runtime constructor to support additional codecs, the GUI must also be configured to support these codecs and to generate the associated on-disk file fragments for each codec. This is because the runtime service must negotiate the audio codec for the interaction session before it knows which specific Announcement ID or variable parts are going to be played.

Hence, when the runtime service is configured to support any additional encodings other than µ-Law, then the GUI and associated back-end announcement management processes must also be configured to generate those encoding-specific files for all file, variable-part, and plural fragments.

By convention, the following suffixes are used:

(plural) Fragment Object

When type = plural the following keys apply:

Which plural- strings are required will depend on the language and it’s codec implementation. Refer to the relevant variable parts codec for information on which plurals are required.

The values of the plural- keys are relative file names and are interpreted identically to the file attribute.

When location is after (or is not present), this means that the plural fragment occurs after a previous integer variable part. This is the normal behavior in English and in most languages.

For example, the following is a common construction for a Dollar/Cents balance using two variable parts:

{
    "1": {
        "play_list": {
            "English": [
                { "type": "variable-integer" }, 
                { "location": "after", "plural-other": "Dollars", "plural-1": "Dollar", "type": "plural" }, 
                { "file": "And", "type": "file" }, 
                { "type": "variable-integer" }, 
                { "location": "after", "plural-other": "Cents", "plural-1": "Cent", "type": "plural" }, 
                { "file": "Credit_Remaining", "type": "file" }
            ]
        }
    }
}

Note that the definition requires a variable-integer ether before or after (depending on the value of location).

Note that a simpler alternative to this example is to use the price variable type, assuming that the service logic and the codec both support it.

(variable-part) Fragment Object

When type = variable-part no additional keys apply. The actual type (one of the other variable-* type values) is determined at run-time.

In practice, only one variable part type will make sense in the concept of the constructed announcement. However, the announcement specification does not expressly enforce the type of the variable part, and the service logic may supply a variable part of any supported type.

(variable-integer) Fragment Object

A variable part “integer” value is an integer in the range 0 - 2147483647, although individual codecs may further limit that range.

Out-of-range (including negative) inputs will generate a run-time error and the announcement will not proceed.

The Integer is translated at run-time to a natural language speaking of the number.

Example: Integer variable part 4401 would map in English to:

This would use the following variable part audio files:

(variable-digits) Fragment Object

A variable part “digits” value is a string of digits characters supplied in ASCII.

The supported input characters are 0 - 9, A - F, *, and #.

Unsupported characters will generate a run-time error and the announcement will not proceed.

The characters are spoken in sequence without additional structure.

Example: Digits variable part 700F# would map phonetically in English to:

This would use the following variable part audio files:

(variable-time) Fragment Object

A variable part “time” value is an integer in the range 0 - 2400.

Some codecs may provide additional configuration control over the structure of the output, e.g. over whether the 12 or 24 hour clock is used.

Invalid integers such as 779 will generate a run-time error and the announcement will not proceed.

Example: Time (HHMM) 1320 maps phonetically in English to:

This would use the following variable part audio files:

(variable-date) Fragment Object

A variable part “date” value is an integer in the range 0 - 99991231 with the date being specified in YYYYMMDD format.

Some codecs provide additional configuration control over the structure of the output, such as whether the year is spoken.

Invalid integers such as 211301 will generate a run-time error and the announcement will not proceed.

Example: Date (YYYYMMDD) 20210117 maps phonetically in English to:

This would use the following variable part audio files:

(variable-price) Fragment Object

A variable part “price” value is an integer in the range 0 - 99999999 with the cents value as the last two digits of the number.

Some codecs may provide additional configuration control over the structure of the output.

Out-of-range input will generate a run-time error and the announcement will not proceed.

Example: Price (DDDDDDCC) 440106 maps phonetically in English to:

This would use the following variable part audio files: