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: Eitherfile
/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. Eitherbefore
/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”