Reco Register Grammar

This Reco tool registers a grammar specified by URL with the recognition subsystem. The grammar can be referenced in subsequent tool steps by its identifier. Once a grammar is registered, it can be referenced through its ID on the same session until it is explicitly unregistered with Reco Unregister Grammar. Closing the session or re-initializing it with Reco Initialize will also clear all registered grammars.

The same grammar may be registered with multiple IDs, as the IDs simply represent a "moniker" for the grammar. The behavior of registering a different grammar with an ID that already exists depends on the Override Duplicate ID parameter.

In general, it is recommended to explicitly specify a GrammarID and leave the Override Duplicate ID checkbox checked. This permits optimizing the grammar registration if the exact same grammar is registered multiple times, for example if a subroutine handler is invoked multiple times during a call. Choosing a consistent naming scheme for GrammarIDs does not only simplify handler debugging and maintenance, but also optimizes grammar registration and cache performance. For example: For grammars specific to a handler, use the handler name as prefix to the GrammarID, such as "MyHandler_Gram1"; for common or built-in grammars, use a grammar ID that will be used throughout all (subroutine) handlers for the same grammar.

Built-in grammars have to be registered to create a reference (GrammarID) for it. The resulting Grammar ID will constitute an alias for the built-in grammar with its parameters. Registration is not necessary if the Reco Basic Input tool is used or an inline reference is used in the Reco Input tool. Explicitly registering grammars that are used multiple times is more efficient, though.

When the grammar is registered with Override Duplicate IDs and a grammar with the specified ID already exists, the existing grammar is replaced with the new grammar. Thus, the GrammarID now refers to the new grammar.

Grammars do not have to be explicitly unregistered, as all grammars of a session are automatically unregistered when the session terminates.

Note: Registering the same grammar (URI and parameters) multiple times without an explicit ID (i.e. the subsystem synthesizes an ID), will cause a new reference and ID to be generated for each tool invocation.

Inputs

Interaction

Identifier of the interaction.

Grammar URI

URI of the grammar to activate. The supported schemas and grammar formats are engine dependent. The URI may include a fragment identifier identifying a certain rule in the grammar. Support for fragments depends on the grammar type and (ASR) engine.

Grammar Type

Use this optional parameter to define the media type (MIME type) of the grammar referenced by the URL. If not specified, the recognition subsystem deduces the type from the file extension or the HTTP header. However, in general it’s a good idea to specify the MIME type and not rely on the automatic deduction.

This parameter must be empty for built-in grammars.

If a type is specified that is different from the actual data, the tool will take the Invalid Type exit path. The following are the media types of the engine-agnostic grammar formats:

application/srgs	SRGS ABNF
application/srgs+xml	SRGS GrXML
application/x-jsgf	JSpeech

Grammar Mode

Mode of the referenced grammar. Thus, a grammar with mode "dtmf" is used for DTMF input. The tool will determine the grammar mode from data by default. An error will occur if it is not an engine agnostic grammar.

Note: A grammar cannot apply to more than one mode (thus, "voice dtmf" is not a valid mode).

Grammar Weight

The bias of this grammar in relation to other grammars, specified as a positive floating-point number. A value greater than 1.0 positively biases the grammar, and a value less than 1.0 negatively biases the grammar. The default value is 1.0. Not all engines support this and it is ignored if not supported.

Registration Mode

Controls when the grammar is sent to the ASR server:

Sync: If the grammar is not already on the ASR server, the grammar is sent to the server and compiled. The tool blocks until the registration succeeded. This most is best for testing as errors will be reported immediately.

Async: If the grammar is not already on the ASR server, the grammar is sent asynchronously and compiled in the background. The tool returns immediately. This most is best to register large grammars whose compilation may take a while and which aren’t immediately used.

Lazy: The grammas is not sent to the ASR server (and no ASR port is allocated if the interaction doesn’t yet have one). The grammar is sent to the ASR server the first time it is used for input. This is the most efficient mode, but grammar compilation errors may not be noticed until the first input is attempted with it.

Grammar ID

ID of the grammar. If not specified, the tool will synthesize one. The grammar IDs must only consist of alphanumeric characters as well as ‘$’ and ‘_’. IDs starting with ‘$’ are reserved for synthesized and other special IDs.

Override Duplicate ID

Specifies behavior if the session already has a grammar with this the specified GrammarID: Leave this box checked if you want pre-existing grammars to be overwritten by new grammars using the same ID. I.e., if a grammar with the specified ID has already been registered for this session, the old grammar will be un-registered and replaced with the new grammar.

Clear this box if you do not want older grammars to be overwritten. If this box is unchecked, then if a grammar with the specified ID has already been registered for this session, the tool will exit via the Failure exit path with error code "error.com.inin.grammar.id.duplicate".

Outputs

New Grammar ID

Grammar ID of the grammar. If a Grammar ID is specified as an Input, the same value is returned. If none is specified, this parameter returns a synthesized ID.

Error Code

If the registration fails, this output parameter contains an error code in the form of a VoiceXML event. This will be an empty string if no error occurred.

Error Text

If the registration fails, this output parameter will contain a simple textual description of what went wrong (e.g. reason for compilation error).

Exit Paths 

Success

This path is taken if the grammar specified by the URL was successfully registered. This path may be taken even if the grammar is not actually valid as the engine may only fetch the grammar when it’s actually used.

Failure

This path is taken if some other error occurred.