Log

Overview

The Log object is a configurable dialog component that writes application-level logging information. This information may be written to a log file, to the media platform (typically some call detail record file), to a custom database, to the system database, or to the OSDM log, in case OSDM objects are used in the application. Logging information may contain arbitrary dynamic content such as caller input, data retrieved from back-ends, etc. It may be written out at any point during a session, or after the session has ended.

The Object Definition below covers the configuration of the Log object with VoiceObjects Desktop. For information on how to define this object type using VoiceObjectsXML refer to the VoiceObjectsXML Definition paragraph.

The Log object belongs to the object category Resources.

Dialog Flow Scenario

The following dialog flow example describes a simple Log object from the Prime Insurance Portal:

Object – Caller	Dialog Flow
	Please say the make and model of your car
Caller	Ford Thunderbird
	Logs “Make = Ford / Model = Thunderbird” to a log file

Object Definition

The Definition of the Log object provides one section:

· Log
To define the set of Log items.

For further details regarding additional object configuration refer to Pre-/Postprocessing, Event Handling, Tuning, and Properties in this Object Reference.

Log

The Log section contains at least one Log Item that writes log information to one of various configurable destinations. Different log items within the same Log object may log to different destinations. The log information can be a simple text or a combination of text and/or Variable, Collection, Expression, Script, and Layer objects.

A log definition may contain any number of individual Log items. If it has multiple Log items, they are processed in the order in which they are specified.

Except of the actual log statement described below, for each Log item the following properties can be specified:

Property	Description
Label	Optional parameter to identify the Log item in a list.
Layer	Optional parameter to indicate the layer that the Log item belongs to. For more information on layers, see the Layer object in this Object Reference or Chapter 7 – How to Use Layers in the Design Guide.
Occurrence	Enables you to log different information depending on how often the Log object has already been visited. Always means that regardless of the number of previous visits, the respective Log item is always processed. Only once means that the Log item is only processed the first time the Log object is visited. And If >= N means that the Log item is processed only if this is at least the N^th time that the Log object has been visited. Note that even if no Log item remains, the Log object’s postprocessing (if defined) will still be processed.
Category	Identifies the message category that the respective Log item belongs to. Categories are intended to provide a filtering mechanism by which designers can classify individual log messages. Some messages may only be relevant during development, while others are important in a deployed service for statistics or billing purposes. Only Log items that belong to categories activated in the corresponding service are processed at call time. This makes it very easy to enable or disable groups of messages without actually having to modify the application itself. For more details, see Chapter 2 – Configuring Servers and Services in the Deployment Guide.
Destination	Indicates where the log information is written to. The following destinations are available (see also Usage Examples): Default Indicates that the default destination defined in the corresponding service is used. For more details, refer to Chapter 2 – Configuring Servers and Services in the Deployment Guide. Custom DB Indicates that the Log item writes to a custom table in a database. When using this destination, the Log item needs to contain SQL code appropriate for the database system used. The SQL is passed on to the database after all object references within it have been evaluated. Note that even though no explicit restriction is placed on the SQL code, only INSERT or UPDATE statements are recommended as there is no mechanism to capture return data provided by SELECT statements. Only a single SQL statement may be provided per Log item. If multiple statements are required, these need to be split over multiple Log items that are processed in sequence. The SQL statement must not be terminated by a semicolon. For additional information on how to configure the Custom DB logging database connection, refer to Chapter 1 – Advanced Configuration of VoiceObjects in the Administration Guide. Log File Indicates that the Log item writes to a log file. A separate log file is created for each service. These files can be accessed via the Control Center as described in Chapter 3 – Managing Servers and Services in the Deployment Guide. Log OSDM Indicates that the Log item writes to the OSDM log, in case the application makes use of OSDM objects and OSDM logging is activated and defined properly in the corresponding Service object. For more information on this, refer to Chapter 2 – Configuring Servers and Services in the Deployment Guide. Media Platform Indicates that the Log item writes to the media platform log by using the VoiceXML <log> tag. Any information sent to this destination is included in the VoiceXML page rendered by the server. It can therefore be viewed in the Debug Viewer and in session tracing files, making this a useful destination for debugging with or without a media platform. System DB Indicates that the Log item writes to the system database; the information is stored at the end of the call. There is a buffer of at most 4000 characters per dialog to which new Log items are appended. For additional information on how to configure the System DB logging database connection, refer to Chapter 1 – Advanced Configuration of VoiceObjects in the Administration Guide. For examples of how to use the different logging destinations, see the Usage Examples paragraph below.

Log items are processed in the order in which they are defined in the Log object. If one of them encounters problems, the others are still processed. Problems may occur e.g. if a database cannot be reached, the SQL code has an error, or a file cannot be written to. The event Error Internal is generated, so the problem can be handled as is appropriate for the application. For more details, refer to Event Handling in this Object Reference.

i8 Note: If a problem occurs within any of the Log items in a Log object, then no VoiceXML code can be rendered by the Log object. This implies that none of the Log items with destination Media Platform will be able to write out their messages to the media platform. It is therefore recommended to keep Log items with destination Media Platform in a separate Log object.

Log statement

A Log item can be defined by entering plain text in the text area or by inserting new or existing Variable, Collection, Expression, Script, and Layer objects. For more information on how to do this, refer to Chapter 6 – Object Editors in the Desktop for Eclipse Guide and Desktop for Web Guide, respectively.

To insert a new object, drag the appropriate object type from the Object Palette. In Desktop for Web this is done via the context menu.

@8 Tip: To simplify the mapping to the tables of the Infostore Repository you can use wildcards inside a log statement that represent key values from tables, like dialog ID, CRM ID, the ID of the active business task, etc. For a list of these wildcards, refer to Chapter 1 – Welcome to Infostore in the Infostore Guide.

Usage Examples

The following examples show how information entered by the caller, in this case a car make and model, can be logged to the various available destinations.

Log to a file

The default channel for logging is Log File, which writes to a service-specific file that can be accessed via the Control Center described in Chapter 3 – Managing Servers and Services in the Deployment Guide.

The Log item would be defined as follows:

At call time, this creates an entry in the log file <servicename>_Service.log as follows:

[Category: INFO]
[Log Name: Log car data for dialog analysis]
[Label: Log to file]
[Ref ID: 0.129.129:OVAPac16172d00000000f9fb1f02ee_BVO_Log]
[VSN: prime_insurance]
[Dialog ID: OVAPac16172d0000000000000076000000fa08fc0de6]
[TS: 2004-01-12 08:45:46,736]
[DNIS: 022113542765]
[ANI: 0173764658477]
Car make: Chevrolet / Car model: Impala

(Additional line breaks have been added for readability.)

Log to the media platform

Sometimes it is desirable to store logging information together with other information logged by the media platform itself. This can be accomplished using the Media Platform destination, which makes use of the VoiceXML element <log>.

The Log item must be defined as follows:

The VoiceXML code generated at call time looks as follows:

<log>

<![CDATA[

[Category: INFO]

[Log Name: Log car data for dialog analysis]

[Label: Log to file]

[Ref ID: 0.129.129:OVAPac16172d00000000f9fb1f02ee_BVO_Log]

[VSN: insurance]

[Dialog ID: OVAPac16172d0000000000002630000000fb15806e33]

[TS: 2004-03-04 12:29:23,363]

[DNIS: 022113542765]

[ANI: 0173764658477]

Car make: Ford / Car model: Mustang

]]>

</log>

(Additional line breaks have been added for readability.)

Information written to the Media Platform destination can also be viewed in the Debug Viewer and in session tracing files, making this a useful destination for debugging with or without a media platform.

When using the Media Platform destination, it is also possible to use a custom-coded inline <log> tag that is simply copied into the VoiceXML code. This allows designers to make use of custom attributes to the <log> tag, which some media platforms provide.

The example shown here makes use of the custom attribute dest, which defines a destination, in this case bill for billing.

For more information on where the data provided within the <log> element is stored and how to access it, refer to the documentation of the respective media platform.

Log to the OSDM log

When your application makes use of OSDM objects, you can use the Log object to log data to dedicated log files that the OSDM server maintains. Make sure to activate OSDM logging and to set the correct logging destination in the corresponding Service object.

The Log item must be defined as follows:

Log to a custom database

Subsequent reporting is often easiest if the log data is already available in a database. One way of doing this is the Custom DB destination, which writes to custom-defined database tables.

The Log item must be defined as follows:

Note that when using the Custom DB destination, the respective tables need to be created beforehand, and appropriate SQL code needs to be provided within the Log object. Only a single SQL statement may be provided per Log item, and there must not be a semicolon at the end of the statement.

In order for Custom DB logging information to be written out, the Enable Custom DB logging check box in the respective service must be selected. In addition, the server hosting this service must have its Custom DB logging option enabled. Refer to Control Center in Chapter 3 – Managing Servers and Services in the Deployment Guide for a detailed description of how to enable and adjust the Custom DB logging status.

i8 Note: Infostore is required for Custom DB logging. For further information, see the Infostore Guide.

Log to the system database

The other way of logging to a database is the use of the System DB destination. It writes out the log data as part of the System DB logging, which Infostore writes for each call (if so configured).

The Log item must be defined as follows:

The system database provides a buffer for these Log items of at most 4,000 characters per call. At the end of the call, this buffer is stored in the column DLG_LOG within the Infostore Repository. If the limit of 4,000 characters is exceeded during call time, any additional attempts to write to the system database are ignored. Note that the individual Log items are simply appended to each other. Use custom separators to distinguish between individual Log items.

In order for System DB logging information to be written out, the Enable System DB logging check box in the respective service must be selected. In addition, the server hosting this service must have its System DB logging option enabled. Refer to Control Center in Chapter 3 – Managing Servers and Services in the Deployment Guide for a detailed description of how to enable and adjust the System DB logging status.

i8 Note: Infostore is required for System DB logging. For further information, see the Infostore Guide.

VoiceObjectsXML Definition

The Log object is represented by the VoiceObjectsXML element <log>. It has six groups of children.

In addition, the element has the standard attributes described in the XDK Guide.

The <log> element uses the embedded <logItem> element.

Log

Children

· <expression usage=”precondition”> or
<variable usage=”precondition”> or
<collection usage=”precondition”> or
<script usage=”precondition”>
Defines the precondition for the Log object.

· <sequence usage=”preprocessing”>
Defines the preprocessing sequence for the Log object.

· +<logItem>
Defines the list of Log items.

· <eventHandling>
Defines the event handling for the Log object.

· <tuning>
Defines the tuning settings for the Log object.

· <sequence usage=”postprocessing”>
Defines the postprocessing sequence for the Log object.

Example

<log>

<text>Manufacturer = </text>

<text> / Model = </text>

</logItem>

<text>insert into carrequests values (</text>

</logItem>

</log>

LogItem

Attributes

· label
A text string providing a name for the Log item.

· layer
Defines the layer for the Log item. Can either be a reference to a Collection, Expression, Script, or Variable object; or a layer state reference of the form “Layer=State” or “Layer!=State” where “State” is the label of a state for the layer “Layer”.

· category
Defines the category for the Log Item. Legal values are info, debug, error, statistics, billing. If not specified, defaults to info.

· occurrence
Defines the occurrence level for the Log item. Can be always, once, or an integer between 1 and 10. If not specified, defaults to always.

· destination
Defines the logging destination for the Log Item. One of default, mediaPlatform, customDB, file, logOSDM, systemDB. If not specified, defaults to default.
The destination logOSDM is only available when the OSDM integration is licensed.

Children

· +(<output>, <variable>, <expression>, <collection>, <script>, <text>, <layer>)
Defines the string to be logged, as a concatenation of various elements.
Note that a single blank will automatically be inserted between any two consecutive non-text children during import into VoiceObjects Desktop or deployment to VoiceObjects Server in order to ensure proper output behavior.

Example

<text>Manufacturer = </text>

<text> / Model = </text>

</logItem>

Object Interoperability

The following table contains all object types that can reference a Log object:

Icon	Object Name	Use Case Example
	Module	A Log object can be used within the embedded sequence of a Module object.
	Sequence	Most commonly, a Log object is used within a Sequence object in a dialog flow.
	Menu	A Log object can be referenced within each Menu item in a Menu object.
	If	A Log object can be used in either the THEN item or the ELSE item of an If object.
	Case	A Log object can be used in any WHEN item of a Case object.
	Loop	A Log object can be used within the embedded sequence of a Loop object.
	Goto	A Log object can be referenced via a Goto object.
	Hyperlink	A Log object can be the destination of a Hyperlink object.

Object Naming Conventions

In order to leverage the capabilities of the integrated documentation of VoiceObjects it is important to provide intuitive and self-explanatory object names and descriptions.

The name of a Log object should indicate which type of information is logged. The table below lists three examples:

Name	Description
Log car make and model	Logs the car make and model for which the caller wants to get an insurance quote
Store billing record	Stores call data into a billing record via the <log> tag
Update caller profile	Augments the caller’s profile to include the interactions in the current call