Mapping File & Rules

Introduction

When using file based configuration, the Announcements JSON Mapping file contains a single RFC 8259 syntax JSON Object.

This file must be named mapping.json.

It exists in the directory whose location is configured as <audio_dir>.

All other file paths are relative to that directory.

Here is a simple example containing two announcement definitions:

{
    "10624": {
        "play_list": {
            "English": [{
                "file": "Menu_Prompt",
                "type": "file"
            }],
            "German": [{
                "file": "Menu_Prompt",
                "type": "file"
            }]
        }
    },
    "25046": {
        "play_list": {
            "English": [{
                "file": "You_Entered",
                "type": "file"
            }, {
                "type": "variable-part"
            }],
            "German": [{
                "file": "You_Entered",
                "type": "file"
            }, {
                "type": "variable-part"
            }]
        },
        "description": "en- You entered <Some Variable.>"
    }
}

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-ID announcement is simply the concatenation of the individual IDs.

Announcement Object

Each Announcement Object has the following keys:

• play_list - Mandatory Object. See below.
• descrioption - Optional String. Description for display in the GUI. Not used at runtime.

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, this must always be done in the context of a single Language Name.

If the service logic did not provide a preferred Language Name, then the constructor must choose a default Language Name.

Each interaction is always performed in the context of a single Language Name, it is not permitted to mix Language Names.

The same Language Name is used for all Announcement ID mapping, and also in the construction of all relevant Variable Parts.

By convention, all Language Names are written with initial capitals, and use an underscore _ character if a space is required.

If variable parts are used, then the Language Name must exactly match the language name key for the variable parts codec. Refer to the per-Language codec documentation.

Fragment Objects

Each Fragment Object has the following keys:

• type: Mandatory String: Either file / variable-part / plural / silence.

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

(file) Fragment Object

When type = file the following keys apply:

• file: Mandatory String. The relative file path for the audio fragment.

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:

• .ul: raw ITU-T REC G.711 µ-law (8000 Hz sample rate, 8 bits per sample, mono).
• .al: raw ITU-T REC G.711 A-law (8000 Hz sample rate, 8 bits per sample, mono).
• .amr: 3GPP TS 26.073 Adaptive Multi-Rate [Narrowband] (AMR-NB) (8000 Hz sample rate, mono).
• .awb: ITU-T REC G.722.2 Adaptive Multi-Rate Wideband (AMR-WB) (16000 Hz sample rate, mono).

(plural) Fragment Object

When type = plural the following keys apply:

• location: Optional String. Either before / after (default).
• plural-0: Optional String. File to use if the Integer variable part == 0.
• plural-1: Optional String. File to use if the Integer variable part == 1.
• plural-2: Optional String. File to use if the Integer variable part == 2.
• plural-other: Optional String. File to use if the Integer variable part == (any other value).

The plural-0 and other attribute values 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-part" }, 
                { "location": "after", "plural-other": "Dollars", "plural-1": "Dollar", "type": "plural" }, 
                { "file": "And", "type": "file" }, 
                { "type": "variable-part" }, 
                { "location": "after", "plural-other": "Cents", "plural-1": "Cent", "type": "plural" }, 
                { "file": "Credit_Remaining", "type": "file" }
            ]
        }
    }
}

Note that the definition does not pre-specify the variable part types. However the service logic must supply integer values at runtime, otherwise a runtime error will occur when the plural fragment selection is perormed, and the announcement will not proceed.

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, and assuming that the desired currency is “Dollars” (which is hard-coded into the variable part “Price” type).

(silence) Fragment Object

When type = silence the following keys apply:

• duration_ms: Mandatory Integer. The duration of the silence, in milliseconds.

(variable-part) Fragment Object

When type = variable-part not additional keys apply.

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 Parts

The five supported types of variable parts are:

• Integer
• Number Digits
• Time (HHMM)
• Date (YYMMDD)
• Price (DDDDDDCC)

Construction of variable parts requires an appropriate language codec with an key which exactly matches the language name specified by the service logic.

Integer

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 maps (in English) to:

• “4”
• “Thousand”
• [100ms Silence]
• “400”
• “And”
• “1”

Number Digits

A variable part “Number 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: Number Digits variable part 700F# maps (in English) to:

• “7”
• “0”
• “0”
• “F”
• “Hash”

Time (HHMM)

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 (in English) to:

• “13”
• “20”
• “PM”

Date (YYMMDD)

A variable part “Date” value is an integer in the range 0 - 991231.

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

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

Example: Date (YYMMDD) 210117 maps (in English) to:

• “January”
• “17”
• [140ms Silence]
• “2000”
• “21”

Note that the input format supplies only a two-digit year. Most codecs will expand this to a four-digit year. Refer to the individual language codec documentation for more details.

Price (DDDDDDCC)

A variable part “Price” value is an integer in the range 0 - 99999999.

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 (in English) to:

• “4”
• “Thousand”
• [100ms Silence]
• “400”
• “And”
• “1”
• “Dollars”
• “And”
• “66”
• “Cents”