5Configuring Events and Commands

Configuring Events and Commands

This chapter provides information about configuring events and commands for session communications, such as for Siebel CTI, to serve your business needs. It includes the following topics:

• About Events and Commands

• Special Events for Device Events

• Special Commands for Device Commands

• Event Handlers

• Event Responses

• Event Logs

• Commands

• Command Data

About Events and Commands

This topic provides information about events and commands. It contains the following information:

• Communications Definition Data in the Database

• Communications Data Sets

• Event and Command Definitions

• Event and Command Parameters

• Wildcard Characters in Event and Command Parameters

You can customize the way Siebel Communications Server operates for functions supported by the Communications Session Manager server component:

Note: Communications events and commands apply only to communications involving interactive drivers that control communications toolbar functionality, such as for the voice channel.

• You can customize the way Communications Server handles events received from the communications system, such as your CTI middleware. Examples of events are when an inbound work item such as a voice call or email message is routed to an agent, when the agent accepts an inbound work item, when an agent completes a conference call, and so on.

• You can customize commands that are to be sent from Communications Server to the external communications system, or that are to invoke some other function. Examples of commands are when an agent accepts an inbound work item, initiates an outbound work item, transfers a work item, and so on.

You can customize event or command definitions, for example, to attach different types of data to incoming, outgoing, or transferred communications work items.

For an overview of communications configuration data, see About Communications Configuration Data.

For information about how to use views in the Administration - Communications screen to modify events and commands, see Defining Communications Commands and Defining Communications Events.

Communications Definition Data in the Database

The Siebel database contains configuration data that helps determine how your communications system is integrated with your Siebel application. Among other functions, the communications configuration data:

• Defines how a Siebel application handles events received from the communications system

• Defines how commands are generated and sent from the Siebel application to the communications system

• Defines the appearance and availability of commands in the Communications submenu in the Siebel application, by specifying hot keys, menu command titles, menu item sequence, and so on

Note: The events recognized by the communications driver and the commands supported by the driver are a subset of those supported by the communications system, such as your CTI middleware.

To customize the communications configuration, you must understand your call center’s workflow model, as well as the key business objects for your Siebel application.

You customize communications features by editing or entering data in a series of views in the Administration - Communications screen, as described in Views for Communications Administration.

Communications Data Sets

A communications data set defines the commands, events, and associated data passing between the elements of your communications system, such as between your CTI middleware and the communications-enabled Siebel application that an agent is running. Events and commands have attributes and corresponding data.

Data set attributes can be supplied by:

• External modules such as call control tables, campaign manager modules, predictive dialers, voice response units, call routers, and so on.

• Siebel features or modules that play a role in supporting communications received from external systems, for example, Siebel CTI, Siebel Email Response, Siebel Workflow, Siebel business service methods, and so on.

Each attribute has a name and contains associated data, such as the telephone number for the caller or for the caller’s organization.

To see examples of communications data sets, you can view the Siebel Communications Server log file for the communications drivers that you use and for your external communications systems.

Each type of communications event generated has a unique name and an associated data set. Each event can be handled individually by the communications system. Similarly, commands the Siebel client sends to the communications system can accept parameter strings and data sets.

For example, a command to transfer a work item can, along with parameter data specifying data such as a phone extension, accept any data set. When transferring the work item, the data set might include a service request ID or context information for the agent’s current Siebel view.

Communications Server associates the data set with the work item (attaches data) and sends the data set to the Siebel client of the agent receiving the transferred work item. A screen pop might be generated for the receiving agent, causing the current Siebel view to be displayed with a relevant record, such as a customer’s current service request. For more information about the relationships among the various types of communications configuration data, see Types of Communications Configuration Data.

Event and Command Definitions

This topic lists the types of events and commands supported by Siebel Communications Server, describes the field types for event and command parameters, describes how wildcard characters can be used in parameter values, and notes the form in which parameters are defined in events or commands.

Communications configuration parameters, communications drivers and profiles control the feature set provided by the communications system. Event and command definitions control how and when these features are used, how data attached to communications work items affects application behavior, and so on. Each event or command definition must have a unique name within its type.

Each communications command definition or event definition has a unique name within its type and includes a set of parameters for which values are specified. Each type of event or command, and its supported parameters, is described in detail later in this chapter.

Event and Command Types

The following types of events and commands are defined in a communications configuration:

• Event. Communications Server supports three types of event definitions:

• Event handler. Defines how the Siebel client application responds to events in the communications system. Specifies a response to execute when an event handler matches an event. For more information, see Event Handlers.

• Event response. Determines a specific response to an event that matched the event handler that invokes the response. For more information, see Event Responses.

• Event log. Defines Siebel log-generation rules for communications events. For instance, events might be logged as activities (Action business component) or logged as another type of record. For more information, see Event Logs.

• Command. Defines communications commands that can be invoked in the Siebel application and specifies how they are to appear in the application. For more information, see Commands.

• Command data. Defines data associated with a communications command that is invoked. For more information, see Command Data.

Event and Command Parameters

This topic provides general information about parameters that you can define for your event and command definitions.

Field Types for Event and Command Parameters

Parameters for each type of event or command use one of the following field types:

• Characters (letters, numerals, _ (underscore), and special characters used in macro-expansion)

  Macro expansion can be used in fields of character type, as described in Using Macro Expansion for Character Fields. You can use the macros described in Macros for Parameter Values.

• Boolean (allowable values are True and False)

• Numeric (numerals 0 through 9)

Forms of Event and Command Parameters

Parameters of character type can be one of the following forms:

• Single parameter

  The parameter must be unique within the definition.

• Multivalue

  The parameter name does not have to be unique within the definition. Multiple instances of a multivalue parameter can be defined; each instance has a different value.

• Group of subparameters

  The group parameter name must be unique within the definition, but multiple parameter instances can be defined, each specifying a unique subparameter. For instance, if you have parameters called Filter.A and Filter.B, then A and B are subparameters of the group parameter Filter.

The following table illustrates the usage of parameters of the three forms of character fields. Parameters must be specified in a form similar to what is shown in this table.

Table Event and Command Parameter Forms

Parameter Name	Parameter Value
SingleParam	Value
MultiValueParam	Value1
MultiValueParam	Value2
GroupParam.SubParam1	Value
GroupParam.SubParam2	Value

Wildcard Characters in Event and Command Parameters

The wildcard characters asterisk (*) and question mark (?) can be used within communications event or command parameter values of character type.

Use the wildcard characters to perform pattern matching on communications event data field values or on Siebel database field values. Such matching can help determine which event or command is to be invoked.

Separately, asterisk (*) matches zero or more characters, and question mark (?) matches exactly one character. You can use question mark and asterisk together (?*) to match field values when the corresponding field value must not be empty. This combination of wildcard characters matches one or more characters.

Note: The characters asterisk (*) and question mark (?) do not function as wildcards for event or command parameters that pass parameters to a Siebel business service, a Siebel SmartScript, or a Siebel VB or Siebel eScript script.

Special Events for Device Events

This topic describes special events, which are available for any communications configuration and are independent of the communications driver. Special events can be specified as device events in event handlers.

This topic contains the following information:

• Special Event Attributes

• List of Special Events

For more information about device events, see Defining Communications Events, and see the description for the DeviceEvent parameter in Event Handler Parameters. For more information about defining event handlers, see Event Handlers.

The special events are not received from the communications system, such as CTI middleware, as are many other communications events for which a device event is specified.

Note: Special events are primarily used for defining event handlers in your communications configuration. However, you can also invoke them from scripts written using Siebel VB or Siebel eScript.

When using special events, you use WorkItemID, instead of SiebelWorkItemID, to refer to work item attributes. For example, you might define an event handler as follows:

[EventHandler:OnWorkItemStarted]
   DeviceEvent = "@PreWorkItemStartedEvent"
   FilterSpec = "[$GetWorkItemAttr(WorkItemID, ANI)] IS NOT NULL"

Many of the special events correspond to client handle methods and include work item attributes. For more information, see Work Item Attributes. For more information about the client handle methods, see Methods of ISC_CLIENT_HANDLE.

Special Event Attributes

Many of the special events shown in the following table have some or all of the following attributes:

• ChannelType. The language-independent value representing the channel type of this work item.

• ProfileName. The communications driver profile for which this work item is applicable.

• WorkItemID. The ID number of this work item.

• WorkItemMode. The mode of this work item, where 1 represents an inbound work item, and 2 represents an outbound work item.

List of Special Events

The special events, which have names that start with the symbol @, are described in the following table.

Table Special Events

Event Name	Description
@PreIndicateNewWorkItemEvent @PostIndicateNewWorkItemEvent	Respectively, these special events correspond to just before, and just after, the client handle method IndicateNewWorkItem is invoked. These special events have the following attributes: ChannelType ProfileName WorkItemID WorkItemMode
@PreWorkItemReleasedEvent @PostWorkItemReleasedEvent	Respectively, these special events correspond to just before, and just after, the client handle method WorkItemReleased is invoked. These special events have the following attributes: ChannelType ProfileName WorkItemID
@PreWorkItemResumedEvent @PostWorkItemResumedEvent	Respectively, these special events correspond to just before, and just after, the client handle method WorkItemResumed is invoked. These special events have the following attributes: ChannelType ProfileName WorkItemID
@PreWorkItemStartedEvent @PostWorkItemStartedEvent	Respectively, these special events correspond to just before, and just after, the client handle method WorkItemStarted is invoked. These special events have the following attributes: ChannelType ProfileName WorkItemID
@PreWorkItemSuspendedEvent @PostWorkItemSuspendedEvent	Respectively, these special events correspond to when the client handle method WorkItemSuspended is invoked. These special events have the following attributes: ChannelType ProfileName WorkItemID
@RuntimeEvent	Corresponds to a Siebel run-time event, which was defined in the Administration - Runtime Events screen. This special event has the following attributes: Context. The business service context. ActionSet. The name of the action set. Action. The name of the action. EventId. The ID of the run-time event. Event Name. The name of the run-time event (for example, SetFieldvalue). Sub Event. The name of the subevent. Event Type. The event type specified in the Object Type field. Object Name. The object name. BusObjName. The business object name. BusCompName. The business component name. ActiveRowID. The current active row ID of the business component. ViewName. The current view name. For more information about configuring run-time events, see Siebel Personalization Administration Guide.

Special Commands for Device Commands

This topic describes special commands, which are available for any communications configuration and are independent of the communications driver. Special commands can be specified as device commands in commands.

This topic contains the following information:

• List of Special Commands

• Special Command Parameters

• Examples of Special Commands

For more information about device commands, see Defining Communications Commands and see the description for the DeviceCommand parameter in Command Parameters.

For more information about defining commands, see Commands.

The communications driver does not receive these commands and so does not pass them to a system such as CTI middleware, as with many other device commands that you specify. Some special commands might, however, require another module.

Note: Special commands are primarily used for defining commands in your communications configuration. However, you can also invoke them from scripts written using Siebel VB or Siebel eScript.

Each special command allows attachment of any user-defined key or value pair to the work item. Within the communications configuration, these key or value pairs are represented by event or command parameters and the associated parameter values.

Commands in which special commands are specified as device commands support the event and command parameters documented in Configuring Events and Commands. In your command definitions, you can specify custom subparameters for command parameters of type Group.

List of Special Commands

The special commands, which have names that start with the at sign (@), are described in the following table. In this table, an asterisk (*) before a parameter name means that the parameter is optional for this command. Parameters for these special commands are described in the table in Special Command Parameters.

Table Special Commands

Command Name	Parameters	Description
@Associate	bus_comp_field	Updates a work item’s tracking object. This object is specified using the event logging feature and the AfterWork event log parameter. Note: In order for a command to be enabled that is based on the @Associate special command, all applicable event log definitions must include the AfterWork parameter. AfterWork.'ACD Call Duration' = "{@WorkDuration}" For more information about the AfterWork parameter, see Event Logs. To associate the tracking object to an account record, for example, the associated command data definition includes parameters like these, to specify the business component and field: BusComp = "Account" Param."Account Id" = "{Id}" Parameter names enclosed in single or double quotes, as shown for Param."Account Id", are interpreted as field names. Values for such a parameter are interpreted as field values, for which macro-expansion is supported. (The quotes enclosing the parameter values in this example are not part of the parameter values.) The @Associate command always operates on the selected work item: the work item with the current focus, which an agent has selected from the Work Items list in the communications toolbar. For more information about event logging, see Event Logs.
@CreatePopupFrame	*AppletMode *Dimension *PageURL	Causes the browser to display a window in which to display content. The browser window content can be filled in as appropriate for a specified URL, based on what you specify for the PageURL parameter. Alternatively, it can display an applet. For example, a command definition using @CreatePopupFrame as the device command might have an associated command data definition that provides a URL to be displayed in the window, for example: Param.PageURL = "http://www.example.com" The URL can also be specified without the prefix http://, if the URL begins with www. A third-party company integrating with Siebel applications can use this method to open a new browser window and connect to its own Siebel application interface for integration purposes. In order to display an applet, the command data for a command using @CreatePopupFrame must include the following parameters: Param.AppletMode = "mode_name" SelectParam = "True" SelectApplet = "applet_name" where mode_name is either Edit or Base (use Edit for form applets and Base for list applets) and applet_name is the applet name in Siebel Tools. Base is the default value for AppletMode. The browser window dimensions can be specified using the Dimension parameter. For example, the following parameter creates a window with dimensions 500 by 300 pixels: Param.Dimension = "500x300" If the Dimension parameter is not defined, then the dimensions are determined by the applet specified using SelectApplet, or by the browser.
@InvokeSWECommand	SWECommand	Invokes a command on the Siebel Web Engine (SWE). The SWE command is specified using the SWECommand parameter. For example, for the command SendFaxGroup, which uses @InvokeSWECommand as the device command, this command data parameter is defined: Param.SWECommand = "Send Fax (SWE)" All of the Send commands (Send Email, Send Fax, Send Wireless Message, and Send Page) are invoked using @InvokeSWECommand.
@OpenView	View	Navigates the Siebel application to the specified view. In the command data definition, specify the view name as defined in Siebel Tools, for example: Param.View = "Service Contact Detail View"
@UpdateRecord	bus_comp_field	Updates a database record for the current business component. For example, if the current view is based on the Service Request business component, then you can change a status-related field for this business component. In the command data definition, specify parameters based on what business component field to update and what values the field supports. For example: BusComp = "Service Request" Param.'Status' = "Pending"
@ViewWorkObject	View	Views a work-tracking object for a work item. Navigates to the view, such as a view in the Activities screen, where you can view the tracking object’s record. @ViewWorkObject can be invoked from a business service, but not directly from a script. Note: In order for a command to be enabled that is based on the @ViewWorkObject special command, all applicable event log definitions must include the AfterWork parameter. AfterWork.'ACD Call Duration' = "{@WorkDuration}" For more information about the AfterWork parameter, see Event Logs. A command data parameter with the name Param.View must exist and must contain the name of the view in which to view the tracking object. For example, if the tracking object is Action (for activities), then this record can be found in the view specified as follows: Param.View = "Activity Attachment View" Note: The view must be based on the same business component specified in the event log. The @ViewWorkObject command always operates on the selected work item: the work item with the current focus, which an agent has selected from the Work Items list in the communications toolbar. Note: Work-item duration is updated for the work-tracking object (such as an activity record) when a work item is released. This update might conflict with changes made by the agent. Consequently, an agent viewing a work-tracking record must save any changes before releasing the work item. To make changes after releasing the work item, the record must first be refreshed.

Special Command Parameters

The following table lists special command parameters and their usage. The previous table identifies the commands that use each of these parameters. Within the communications configuration, special command parameters and values can be specified within command data definitions as subparameters of the Param parameter. For more information, see Command Data.

Table Parameters for Special Commands

Command Parameter	Description
AppletMode	For @CreatePopupFrame, specifies the mode for an applet to be displayed in the new browser window.
Dimension	For @CreatePopupFrame, specifies the dimension of the new browser window.
PageURL	For @CreatePopupFrame, specifies a URL to be displayed in the new browser window.
SWECommand	For @InvokeSWECommand, specifies a Siebel Web Engine (SWE) command to be invoked.
View	For @ViewWorkObject, specifies the name of a view.

Examples of Special Commands

This topic provides examples of the special commands.

Example of @Associate Special Command

The following table and the second table in this topic provide an example command using the @Associate special command. This example defines a command and associated command data that creates an association between the current activity object and the current account object. The example command is enabled only when the agent is working with accounts and when a work-item tracking object exists. For more information, see the description for @Associate in List of Special Commands.

Table Command: Associate Account

Parameter Name	Parameter Value
DeviceCommand	@Associate
Hidden	True

The following table shows a command data definition for this command definition.

Table Command Data: Associate Account

Parameter Name	Parameter Value
BusComp	Account
Param."Account Id"	{Id}

Example of @View Work Object Special Command

The following table and the second table in this topic provide an example command using the @ViewWorkObject special command. This example defines a command and associated command data that allows a user to view the work-item tracking record. The command specifies the menu item to be used for viewing the record and assigns the command to the hot key SHIFT+F8. The command is enabled only when a work-item tracking object exists. For more information, see the description for @ViewWorkObject in the table in the Special Commands topic.

Table Command: ViewWorkObject

Parameter Name	Parameter Value
DeviceCommand	@ViewWorkObject
HotKey	SHIFT+F8
MenuPosition	8
Title	View Work Item Object

The following table shows a command data definition for this command definition.

Table Command Data: ViewWorkObject

Parameter Name	Parameter Value
Param.View	Activity Attachment View

Event Handlers

This topic describes event handlers. It contains the following information:

• Event Handler Parameters

• Handling an Inbound Call Received by an Agent

Communications events from the communications system are directly passed to Siebel Communications Server, in particular the Communications Session Manager, for further processing.

Note: Each event log specified in a single event response must be unique. (Event logs can be specified in the All Event Handlers view, but they are actually associated with the event response that is associated with the event handler.) For more information, see Event Responses.

Event Handler Process Overview

Communications events involve the following phases of activity:

1. An event or action, such as a phone call being disconnected, occurs in the communications system, such as a telephony switch. The switch forwards events to a communications middleware server, such as a CTI middleware server.

2. The middleware server, such as CTI middleware, forwards the event to the Communications Client business service.

3. The Communications Client business service processes the event and executes any actions defined in the configuration data in the database, or forwards events to business service methods or to Siebel VB or Siebel eScript code.

   By working with event data in the Administration - Communications screen, you can define the actions to be performed when a particular communications event is received. Such actions are invoked immediately upon receipt of such an event.

   Event handlers specify what kind of event from the communications system is processed and specify which event response is called as a result.

Event Handler Parameters

The following table describes the parameters available in event handlers in the communications configuration data. The value of the Macro column indicates whether macro expansion applies to the parameter.

Table Event Handler Parameters

Parameter	Type	Macro	Description
DeviceEvent	Char	Not applicable	Communications device-generated event name. Device commands that are recognized by the communications driver are specific to particular communications systems. Possible values include the device events supported by your communications driver. Note: Do not specify this parameter as an event handler parameter. Rather, specify the device event for the event handler directly, using the Administration - Communications screen. This parameter is used in DEF files that you export to or import from.
Filter	Group	Not applicable	Event data-field filter. This works like a standard IsLike() function. All filter results are logically joined by AND to determine if the event matches this event handler. You can filter data received from the communications driver, data attached to the work item by the channel manager, or data attached or modified by an agent who previously handled the work item, such as a transferring agent. The Filter and FilterSpec parameters can be used together to evaluate event data-field data received with the device event associated with this event handler. Evaluations using the Filter parameter (AND conditions) occur before evaluations using the FilterSpec parameter (compound predicate). The fields available for filtering depend on the communications driver that you are using.
FilterSpec	Char	Yes	Event data-field filter that supports simple or complex queries. Filter results are evaluated using a compound predicate that can include standard query operators to determine if the event handler matches the event. FilterSpec queries use standard comparison operators, including: = LIKE AND OR EXISTS > < >= <= For example: FilterSpec = "[attr1] IS NOT NULL OR [attr2] LIKE 'value*'" where attr1 and attr2 are event data fields and value represents part of a comparison value for attr2. In this example, the event handler is evaluated for a match if attr1 is not empty or if attr2 is like the value of value*. Here is another example: FilterSpec = "[@UserName]='SADMIN'" In this example, @UserName is macro-expanded before the query is performed. The Filter and FilterSpec parameters can be used together to evaluate event data-field data received with the device event associated with this event handler. Evaluations using the Filter parameter (AND conditions) occur before evaluations using the FilterSpec parameter (compound predicate). For more information, see the descriptions for the Filter event handler parameter and the QuerySpec event response parameter.
Order	Numeric	Not applicable	The order in which event handlers (for which the same device event is specified) are tested against event matching. Each received communications event is checked against all event handlers to determine which response to execute. Event handlers with a lower Order value are checked before those with higher values. The default is 0. The check stops when there is a match. Note: Do not specify this parameter as an event handler parameter. Rather, specify the order for the event handler directly, using the Administration - Communications screen. This parameter is used in DEF files that you export to or import from.
Profile	Char	Not applicable	Name of the communications driver profile that generates the device event associated with this event handler. If a profile is associated with the event handler, then the event handler is evaluated only for events received from the communications driver for that profile. For more information, see Creating Event Handlers. Note: Do not specify this parameter as an event handler parameter. Rather, specify the profile for the event handler directly, using the Administration - Communications screen. This parameter is used in DEF files that you export to or import from.
Response	Char	Not applicable	Name of the event response that executes when a matching event is detected. Note: Do not specify this parameter as an event handler parameter. Rather, specify the event response for the event handler directly, using the Administration - Communications screen. This parameter is used in DEF files that you export to or import from.
ServiceMethod	Char	Not applicable	The name of a Siebel business service and method to be called in order to evaluate the event handler for a match. You can use the ServiceMethod and ServiceParam parameters to supplement or replace filter mechanisms using the Filter or FilterSpec parameters. You can also use this method to execute custom code before executing a specified event response. The business method must set a parameter of Result to a value 1 or 0 (or True or False): 1 (True) indicates that this event handler matches and is executed, and the associated event response is executed. 0 (False) invalidates this event handler; the next event handler is evaluated. Specify the service and method in the form service.method. Optionally, you can use the ServiceParam parameter to provide parameter names and values to pass to the method to be called. For more information, see Using Business Services with Siebel Communications Server.
ServiceParam	Group	Yes	A group of subparameters that are parameters to the Siebel business service method (if any) invoked using the ServiceMethod parameter. You create each parameter that you need in the form ServiceParam.param_name, then specify a parameter value. The parameter name and value are both passed to the service method. Order parameters in the sequence in which they are expected by the service method: ServiceParam.Param1 = "value1" ServiceParam.Param2 = "name" Param1 and Param2 are subparameters of the ServiceParam parameter. For more information, see Using Business Services with Siebel Communications Server.

Handling an Inbound Call Received by an Agent

Communications events provide the following general options for handling device events for calls received by an agent. Such an inbound call can employ events like call incoming or event ringing, or call connected or event established, as defined for a communications system employing CTI.

The following list describes the options for handling device events:

• Handle when call connected after agent answers (default). In this scenario, the agent answers the call, triggering the event handler.

  The phone rings. The agent clicks Accept Work Item. The call connected or event established type of event is received. This event triggers handling such as to perform a query to generate a screen pop. In this case, an agent’s work is not interrupted by an unexpected screen pop.

• Handle immediately, when phone rings. In this scenario, the phone rings, triggering the event handler (before the agent answers the call).

  The phone rings. The call incoming or event ringing type of event is received. The event triggers handling such as to perform a query to generate a screen pop. The agent clicks Accept Work Item, then the connection is established. In this case, an agent’s work might be interrupted by a screen pop when the phone rings, without any notifications or confirmations.

Note: If the user has modified the current record, then this record is automatically committed anytime an agent clicks a button on the communications toolbar or anytime a screen pop is triggered. If the user has not provided values for all required fields, then a pop-up window prompts the user to provide the values to complete the record.

The Siebel sample communications configurations provide examples of some of these scenarios. You can implement other screen-pop behavior using Siebel VB or Siebel eScript.

Example of Using Event Handler to Handle Inbound Call

Here is an example event handler, named InboundCallReceived, that is based on the default inbound call screen-pop scenario previously described in the scenario Handle when call is connected after agent answers. For this event handler:

• Set the Order field to 0 to make sure it takes priority over any other event handlers that might otherwise match.

• Set the Device Event field to event_name, where event_name corresponds to an event such as the agent clicking Accept Work Item.

• Include the following event handler parameter:

  Filter.ANI = "*"

The example event handler is associated with an event response OnInboundCallReceived. Because the Order field is set to 0, this event handler is checked first for any event received where the device event is as specified. The event handler filters the event data field ANI. If this field exists, then the event matches and invokes the event response OnInboundCallReceived.

To handle a call-incoming or event-ringing type of event without waiting for the agent to click Accept Work Item, you can create a similar event handler that triggers immediately when a suitable event occurs. You might name such an event handler ImmediateRingingHandler and invoke a similarly named response.

Event Responses

This topic describes event responses. It contains the following information:

• Event Response Parameters

• Event Response Example

Event responses in the communications configuration data specify how the Siebel client associates response actions with an event. Each event handler specifies a response that corresponds to an event response. Different event handlers can initiate the same event response.

Note: Each event log specified in a single event response must be unique. When you associate event logs with an event response in the Siebel client, the user interface prevents you from associating the same event log more than once. For example, if you have already associated the event log OutboundActivityContactCall, using type Log, then you cannot associate the same event log using another Log Type, such as SingleLog. If you create DEF files to import, then do not specify, within an event response definition, multiple event log parameters that specify the same value. If you do so, then an error is generated when you attempt to import this configuration data.

Event Response Process Overview

In executing the event response, Siebel Communications Server performs the following actions:

1. If a Siebel business service method name is specified, such as to update the customer dashboard, then that method is invoked.

   If the method does not return the required result, such as a value of True (1) for the output argument Continue, then the response stops executing. If an event log of type Log is specified, then that event log is processed. Go to Step 13.

   The business service method can also alter the event data fields that were associated with the work item, such as to add new fields.

   For more information about the parameters mentioned here, see the table in the Event Response Parameters topic.

2. If a Siebel VB or Siebel eScript script name is specified, then that script is invoked.

   If the script does not return the required result, such as Continue, then the response stops executing. If an event log of type Log is specified, then that event log is processed. Go to Step 13.

   For more information about invoking a Siebel VB or Siebel eScript script from an event response, see Integrating with Siebel Scripting Languages, and see the descriptions for the Script and ScriptParam parameters in see the table in the Event Response Parameters topic.

3. If a communications command is specified, then the command is executed.

4. If the UseCtxData parameter is defined and set to True, then Communications Server checks to determine if the event has screen context data attached.

   If screen context data is available, then the corresponding screen and view are displayed. This behavior is applicable only for screen pops and screen transfers. (In addition, the Thread Applet and Thread Field properties must be set for the view in order to support screen pops and screen transfers.)

   If an event log of type ContextLog is specified, then that event log is processed. If ContextLog is not specified, but an event log of type Log is specified, then that event log is processed. Go to Step 13.

5. If the QueryBusObj, QueryBusComp, and QuerySpec parameters are defined, then the query specified by QuerySpec is macro-expanded and executed. If these parameters are not defined, then go to Step 9; otherwise, go to Step 6.

   Step 7 and Step 8 define the views upon which this query is displayed.

6. If there is only one row in the query result from QuerySpec, and if the QueryBusComp2 and QuerySpec2 parameters are defined, then the query specified by QuerySpec2 is macro-expanded and executed. If these parameters are not defined, then go to Step 9; otherwise, go to Step 7.

7. If there is only one row in the query result from QuerySpec, then that row is displayed in the view specified by the SingleView parameter. Any field specified by SingleField is populated with data defined in the parameter value. Go to Step 9.

8. If there are several rows in the query result from QuerySpec, then those rows are displayed in the view specified by the MultiView parameter. Go to Step 9.

9. If the OpenView parameter is specified, then the view is displayed that is specified by OpenView. Go to Step 10.

10. If the AddBusComp, AddBusObj, AddRecordView, AddRecordApplet, and AddField parameters are defined, then the view is displayed that is specified by AddRecordView.

    A new record is created in the applet specified by AddRecordApplet. Any field specified by AddField is populated with data defined in the parameter value. Go to Step 13.

11. If a Siebel SmartScript script name or other data is specified to be passed to Siebel SmartScript, then that SmartScript is invoked.

    For more information about invoking a SmartScript from an event response, see Integrating with Siebel SmartScript and see the description for the SmartScript parameter in the table in the Event Response Parameters topic.

12. If the FindDialog and FindField parameters are defined, then the Search Center appears, populated with search criteria. The Search Center does not appear if the OpenView parameter is also specified as in Step 9.

13. If an event log is associated with this event response, then a log record is created using the object defined in the event log, for example, an activity record.

    Multiple event logs can be associated, one of which matches, depending on how the event response executed. For example:

    • If UseCtxData is invoked, as in Step 4, then a ContextLog log can be created.

    • If SingleView is invoked, as in Step 7, then a SingleLog log can be created.

    • If MultiView is invoked, as in Step 8, then a MultiLog log can be created.

    • If AddBusComp, AddBusObj, AddRecordView, AddRecordApplet, and AddField are invoked, as in Step 10, then an AddLog log can be created.

    • If FindDialog is invoked, as in Step 12, then a FindLog log can be created.

    • Otherwise, a log can be created as specified by Log.

For more information about event logs, see Event Logs.

Event Response Parameters

The following table describes the parameters available in event responses. The value of the Macro column indicates whether macro expansion applies to the parameter.

Table Event Response Parameters

Parameter	Type	Macro	Description
AddBusComp	Char	Not applicable	Business component name to use when adding a new record.
AddBusObj	Char	Not applicable	Business object name to use when adding a new record.
AddField	Group	Yes	Field names and predefined value when adding a new record.
AddLog	Char	Not applicable	Event object to execute if the application navigates to the view and applet specified by the AddRecordView and AddRecordApplet parameters. AddLog determines the Siebel activity record to be created in response to communications events. For an example of using this parameter, see Event Response Process Overview. Note: Do not specify this parameter as an event response parameter. Rather, specify an event log of this type for the event response directly, using the Administration - Communications screen. This parameter is used in DEF files that you export to or import from.
AddRecordApplet	Char	Not applicable	Name of the applet that is displayed, in the view specified by AddRecordView, when adding a new record. If AddRecordApplet is not specified, then the record is created in the first applet that can be inserted which has the same business component as specified with AddBusComp.
AddRecordView	Char	Not applicable	Name of the view that is displayed when adding a new record.
Command	Char	Not applicable	Optionally specifies the name of a command in the communications configuration that is invoked when this event response is invoked.
ContextLog	Char	Not applicable	Event object to execute if screen-context data is used for screen display. Determines the Siebel activity record to be created in response to communications events. For an example of using this parameter, see Event Response Process Overview. Note: Do not specify this parameter as an event response parameter. Rather, specify an event log of this type for the event response directly, using the Administration - Communications screen. This parameter is used in DEF files that you export to or import from.
FindDialog	Char	Not applicable	Find Object name to determine what is displayed in the Search Center if no rows are returned.
FindField	Group	Yes	Find Field names and default values to determine what is displayed in the Search Center if no rows are returned.
FindLog	Char	Not applicable	Event object to execute if the Search Center is displayed, as specified using FindDialog and FindField. Determines the Siebel activity record to be created in response to communications events. For an example of using this parameter, see Event Response Process Overview. Note: Do not specify this parameter as an event response parameter. Rather, specify an event log of this type for the event response directly, using the Administration - Communications screen. This parameter is used in DEF files that you export to or import from.
Log	Char	Not applicable	Event log to use if no other log is specified for an action. Determines the Siebel activity record to be created in response to a communications event. For an example of using this parameter, see Event Response Process Overview. Note: Do not specify this parameter as an event response parameter. Rather, specify an event log of this type for the event response directly, using the Administration - Communications screen. This parameter is used in DEF files that you export to or import from.
MultiLog	Char	Not applicable	Event object to execute if the view specified using the MultiView parameter is displayed. Determines the Siebel activity record to be created in response to communications events. For an example of using this parameter, see Event Response Process Overview. Note: Do not specify this parameter as an event response parameter. Rather, specify an event log of this type for the event response directly, using the Administration - Communications screen. This parameter is used in DEF files that you export to or import from.
MultiView	Char	Not applicable	Name of the view that is displayed if the query result contains more than one row.
OpenView	Char	Not applicable	Name of the view that is displayed, regardless of query results. The view specified by OpenView is displayed only if a view specified by SingleView or MultiView is not displayed.
QueryAfterAnswer	Boolean	Not applicable	A parameter that, when set to True, causes Communications Server to answer the call first and then execute the screen-pop query. When set to False (the default setting), this parameter causes Communications Server to execute the query first and then answer the call. This parameter is valid only for an event response invoked by an event handler that follows the handle immediately model. For more information about screen pops, see Handling an Inbound Call Received by an Agent.
QueryBusComp	Char	Not applicable	Business component name for the query specified by QuerySpec.
QueryBusComp2	Char	Not applicable	Business component name for a second query, specified by QuerySpec2. The second query executes only if this parameter is specified and if the first query (specified by QuerySpec) returns exactly one row. This feature can be used to get screen pops related to campaigns. For example, the first query can locate the campaign that matches the call type, using DNIS to identify the number the caller dialed. The second query can locate the contact (within that campaign) whose work number matches that of the caller, using ANI to identify a caller’s number.
QueryBusObj	Char	Not applicable	Business object name containing the business components specified by QueryBusComp and QueryBusComp2.
QueryFields	Multi	Not applicable	Field names resulting from the business component query specified by QuerySpec. Only the fields specified here are activated when the Siebel application performs the query. Since the same business component is used to navigate to the destination view, you can use this feature to specify the fields required for that view. If nothing is specified here, then the navigation process causes the business component to be queried again. QueryFields can speed up a screen-pop navigation by preventing additional queries of an entire business component.
QueryFields2	Multi	Not applicable	Field names resulting from the business component query specified by QuerySpec2. For more information, see the description of the QueryFields parameter.
QuerySpec	Char	Yes	Standard business component query. The query uses business component field names from the business object and business component specified with the QueryBusObj and QueryBusComp parameters. (No other fields can be specified.) Simple and complex queries are supported, using standard comparison operators, including: = LIKE AND OR EXISTS > < >= <= For example, if QuerySpec is defined as follows, then the query matches records in the current business component (assuming the business component contains the fields indicated) if either the work phone number or the home phone number matches the ANI value for the call: 'Work Phone #'='{ANI}' OR 'Home Phone #'='{ANI}' Alternatively, if QuerySpec is defined as follows, then the query matches records in the current business component (example is for Action business component) if the current user is one of the owners specified for the multivalue field Owned By: EXISTS('Owned By'='{@UserName}') The keyword EXISTS must be used when defining a query specification for a multivalue field.
QuerySpec2	Char	Yes	A second query that might be performed, after the query specified by the QuerySpec parameter. QuerySpec2 queries the business component specified by the QueryBusComp2 parameter. (Both QueryBusComp and QueryBusComp2 specify business components in the business object specified by the QueryBusObj parameter.) The result of the QuerySpec2 query can be used by Siebel SmartScript. For more information on how the query can be constructed, see the description for the QuerySpec parameter.
Script	Char	Not applicable	Siebel VB or Siebel eScript script name to invoke (if specified). Parameters are passed using the ScriptParam parameter. For more information about using Siebel VB or Siebel eScript, see Integrating with Siebel Scripting Languages.
ScriptParam	Group	Yes	A group of subparameters that are parameters to the script method (if any) invoked using the Script parameter. You create each parameter you need in the form ScriptParam.param_name, then specify a parameter value that is passed to the script. The parameter names themselves are not passed to the script. Order parameters in the sequence in which they are expected by the script: ScriptParam.Param1 = "value1" ScriptParam.Param2 = "name" Param1 and Param2 are subparameters of the ScriptParam parameter.
ServiceMethod	Char	Not applicable	The name of a Siebel business service and method to be called. The service and method are specified in the form service.method. Optionally, you can use the ServiceParam parameter to provide parameter names and values to pass to the method to be called. For more information, see Using Business Services with Siebel Communications Server.
ServiceParam	Group	Yes	A group of subparameters that are parameters to the Siebel business service method (if any) invoked using the ServiceMethod parameter. You create each parameter that you need in the form ServiceParam.param_name, then specify a parameter value. The parameter name and value are both passed to the service method. Order parameters in the sequence in which they are expected by the service method: ServiceParam.Param1 = "value1" ServiceParam.Param2 = "name" Param1 and Param2 are subparameters of the ServiceParam parameter. For more information, see Using Business Services with Siebel Communications Server.
SingleField	Group	Yes	When the result from the QuerySpec query is exactly one record, that record can be updated if you provide a field name and predefined field value, using this parameter. For example, in the following event response, QuerySpec likely returns a single record, then SingleField can update the Primary Owned By field to the current agent: [EventResponse:EmailWorkStarted] QueryBusObj = "Email Response" QueryBusComp = "Action" QuerySpec = "Id = '{ActivityID}'" SingleView = "Communication Detail - Response View" SingleField.'Primary Owned By' = "{@UserName}" Log=EmailWorkStarted
SingleLog	Char	Not applicable	Event object to execute if the view specified using the SingleView parameter is displayed. Determines the Siebel activity record to be created in response to communications events. For an example of using this parameter, see Event Response Process Overview. Note: Do not specify this parameter as an event response parameter. Rather, specify an event log of this type for the event response directly, using the Administration - Communications screen. This parameter is used in DEF files that you export to or import from.
SingleView	Char	Not applicable	Name of the view that is displayed if the result from the QuerySpec query is exactly one row. QueryBusComp2, QuerySpec2, and QueryFields2 can be used to query a second business component of the QueryBusObj for a single record.
SmartScript	Group	Yes	Parameter to be passed to Siebel SmartScript. Can include a script name or other data to pass to SmartScript. You can specify any of the following subparameters: SmartScript.CampaignId SmartScript.CampContactId SmartScript.ContactId SmartScript.LanguageCode SmartScript.ScriptId SmartScript.ScriptName Either SmartScript.ScriptName or SmartScript.ScriptId must be specified in order to launch a particular SmartScript. For more information, see Integrating with Siebel SmartScript.
UseCtxData	Boolean	Not applicable	Enables or disables automatic use of screen-context data attached to an event. When UseCtxData is True, and the event contains a Siebel screen bookmark, the bookmark is used to perform a screen pop or screen transfer. The default is False. Note: The size of a Siebel screen bookmark is defined by the middleware and communications driver and might vary according to each vendor.
WorkObject	Char	Yes	Specifies data identifying a work-item tracking database record that can be written to the database. This parameter can make work-item tracking possible even if your communications system does not fully support attaching data to a work item. The WorkObject parameter is not necessary for CTI middleware packages that support call data attachment. This data is passed to the communications driver, which attaches the data to the call without requiring the WorkObject parameter. If you are using a custom driver developed for other middleware, then you might have to use the WorkObject parameter in order to pass work-item tracking data from one agent to another, such as when a call is transferred or made as a conference call. Example: An agent receives a call and creates the activity record for it. When this agent transfers the call to a second agent, the second agent wants access to the same activity record. For the first agent’s session, the row ID of the activity record is encoded, and the call is transferred. If the WorkObject parameter is defined appropriately, then the second agent can continue tracking the call-activity record. Format values for this parameter as follows: bus_obj_name;bus_comp_name;row_ID For activity records, Action is the name of the business object and the name of the business component. Whether you require the WorkObject parameter, and how you define the parameter, depend on your communications system and driver. For example, with Aspect middleware, if variable E is used to store the row ID, then define WorkObject as follows: Action;Action;{E} Whether this parameter definition works as intended depends on whether the communications driver expects to receive data in this form to pass to the receiving agent.

Event Response Example

The following table shows an example of an event response.

Table Event Response: On Inbound CallReceived

Parameter Name	Parameter Value
QueryBusObj	Contact
QueryBusComp	Contact
QuerySpec	'Work Phone #'='{ANI}'
SingleView	Service Contact Detail View
MultiView	Contact List View
FindDialog	Service Request
FindField.CSN	Ask Caller
SingleLog	LogIncomingCallContactFound
MultiLog	LogIncomingCallMultiContactFound
FindLog	LogIncomingCallContactNotFound

In this example, the information specified with the business object and business component parameters is retrieved. Communications Server then performs a query on the phone number retrieved from the ANI event data field, to see if it matches a value in the Work Phone # field in the Contact business component. (SingleLog, MultiLog, and Log are specified using fields, rather than parameters.)

If QuerySpec returns a single record, then the agent is navigated to the service requests view specified by SingleView. The event log LogIncomingCallContactFound, which is specified by the SingleLog parameter, creates a call activity record automatically.

If QuerySpec returns multiple records, then the agent is navigated to the contacts view specified by MultiView. The event log LogIncomingCallMultiContactFound, which is specified by the MultiLog parameter, creates a call activity record automatically.

If QuerySpec returns no records, then the Search Center appears and displays Ask Caller in the CSN field. The event log LogIncomingCallContactNotFound, which is specified by the FindLog parameter, creates a call activity record automatically.

Event Logs

This topic describes event logs. It contains the following subtopic: Event Log Parameters.

Event logs in the communications configuration data define log-generation rules for communications activity. Some event responses have an associated event log.

Note: Each event log specified in a single event response must be unique. Define separate event logs for each such usage context, accordingly. For more information, see Event Responses.

Event Log Parameters

The following table describes the parameters available in event logs. The value of the Macro column indicates whether macro expansion applies to the parameter.

Table Event Log Parameters

Parameter	Type	Macro	Description
AfterWork	Group	Yes	Field names and values, from the log business component, that are used to update the work-tracking log record when the work item has ended or been released. Note: After the work item has been released, the log record that is modified according to the fields specified with this parameter is refreshed when the agent clicks off the record, then clicks on it again.
BusComp	Char	Not applicable	Log business component name.
BusObj	Char	Not applicable	Log business object name.
Display	Boolean	Not applicable	Parameter that, when it is set to True and the current view contains a business component specified in the event log, uses the current business component to add a new log record. The log record appears on the screen immediately and is selected. In order for this parameter to function as intended, the current view must retain the focus. If Display is set to False, then the log record is generated but is not selected, and might not be displayed in the current record set. The default is False. Note: While the work item is active, the agent can modify the log record. After the work item has been released, however, if AfterWork is set, then an agent’s changes might conflict with how the log record was written by the Siebel CRM system software at that time. The agent can click off the record, then click on it again to modify it.
LogField	Group	Yes	Field names and values of the log business component.
QuerySpec	Char	Yes	A query specification for retrieving a record in the business component: If QuerySpec is not defined, then a new record is created for the event log. If QuerySpec is defined and returns a single record, then this record is used for the event log. If QuerySpec is defined and returns more than one record, then a new record is created for the event log.
ServiceMethod	Char	Not applicable	The name of a Siebel business service and method to be called. The service and method are specified in the form service.method. Optionally, you can use the ServiceParam parameter to provide parameter names and values to pass to the method to be called. If ServiceMethod and ServiceParam are specified, then they are executed first when the event log is invoked. If the specified business service method does not return the required result, such as a value of True (1) for the output argument Continue, then the event log stops executing. For more information, see Using Business Services with Siebel Communications Server.
ServiceParam	Group	Yes	A group of subparameters that are parameters to the Siebel business service method (if any) invoked using the ServiceMethod parameter. You create each parameter that you need in the form ServiceParam.param_name, then specify a parameter value. The parameter name and value are both passed to the service method. Order parameters in the sequence in which they are expected by the service method: ServiceParam.Param1 = "value1" ServiceParam.Param2 = "name" Param1 and Param2 are subparameters of the ServiceParam parameter. For more information, see Using Business Services with Siebel Communications Server.
WorkTrackingObj	Group	Yes	Field name and values of a work-tracking object to create. You can retrieve the value of the tracking object from a command. For example, the following parameter defines a custom work-tracking object, called ContactId, whose value is derived from the Id field of the Contact business component. WorkTrackingObj.ContactId = "{Contact.Id}" For a selected work item, this data might then be accessed from a communications command, using the WorkTrackingObj command data parameter. In this example, ContactId becomes a custom work item attribute. Alternatively, if an event log includes a parameter definition like the following, then the text that you specify is displayed in the Work Items list in the communications toolbar. WorkTrackingObj.Description = "your descriptive text goes here" For more information about using these and other attributes, see Work Item Attributes.

Commands

This topic describes commands. It contains the following information:

• Hierarchical Commands (Commands and Subcommands)

• Command Parameters

Commands in the communications configuration data define the appearance and availability of communications commands.

By using the DeviceCommand parameter in a command, you can invoke a command on the communications system or invoke a special command.

• Device commands that are executed by the communications driver. Such commands are specific to particular middleware vendors, or to how Oracle supports communications toolbar interactivity.

• Device commands that are independent of communications drivers. For more information, see Special Commands for Device Commands.

Communications commands might instead invoke a business service method, a SmartScript, or a Siebel VB or Siebel eScript script. For commands, each of these mechanisms is mutually exclusive: invoke only one of these mechanisms in a given command. (Scripts and business service methods take precedence over device commands.) For more information:

• About invoking a business service method, see Using Business Services with Siebel Communications Server and Siebel Communications Server Business Services

• About invoking a Siebel VB or Siebel eScript script, see Integrating with Siebel Scripting Languages.

Hierarchical Commands (Commands and Subcommands)

Communications commands can be defined in hierarchical fashion; you can define group commands that contain subcommands. These subcommands are invoked when the group command is invoked. Grouping or nesting commands using subcommands helps to define the communications user interface in the Siebel application.

For more information about specifying subcommands, see Defining Communications Commands. For more information about how command groups are used in configuring the communications toolbar and menus, see Configuring User Interface Elements

When you specify subcommands within group commands, note the following:

• Commands can have subcommands. A command containing subcommands is sometimes referred to as a group command.

• Do not define invalid recursive subcommand relationships, such as making a subcommand include its parent group command as a subcommand.

• The Subcommands list in the All Commands view specifies the order in which commands are executed. Alternatively, if the command parameter ExecuteAll is set to True, then all subcommands can execute. As with any command, subcommands can execute only when they are enabled. Subcommands that are disabled are skipped and not executed.

• If a subcommand fails when executing, then the remaining subcommands are not executed. However, if the command parameter ExecUntilOK is set to True, then the remaining subcommands are executed until one of them succeeds.

• Subcommands and their order are represented in DEF files that you export by using the command parameter SubCommand_N, where N is the order value for each subcommand.

• At run time, commands that invoke device commands are enabled or disabled based in part on the status of the device command. For more information, see SCCommandFlag and CacheCommandInformation.

• At run time, commands that invoke business service methods rather than device commands are determined to be enabled or disabled by invoking from the applicable business service the method CanInvokeMethod("method_name"), where method_name is your business service method to be invoked. If True is returned, then the method can be invoked. If False is returned, then the method cannot be invoked and the command is disabled.

• Several command parameters are used to determine whether a group command or subcommand matches and can be executed. Such command parameters include AllViews, CmdChannelOnFocus, FilterSpec, OnEditControl, and View.

• Several command data parameters are also used to determine whether a group command or subcommand matches and can be executed. Such command data parameters include BusComp, BusObj, Filter, and RequiredField.

• Commands specifying subcommands cannot also specify a device command or business service method.

• If you require a command that executes both a device command and a business service method, then define a group command where ExecuteAll is True and where two subcommands are specified. Define one subcommand to execute a device command, such as a make-call command, and define the other subcommand to invoke your business service method. If you need command data parameters, then create command data definitions and associate them with the subcommands.

• In some cases, a group command must not have command data associated with it. If a group command is at the top (highest) level (is not itself a subcommand), or if a group command is also a subcommand and ExecuteAll is set to True for its parent group command, then command data might be associated. However, in the latter case, if ExecuteAll is not set to True for the parent group command, then do not associate command data with the child group command.

• The command parameter SelectApplet (and related parameters such as SelectBusObj, SelectBusComp, SelectView, and so on) can be used to display a dialog box that pertains to all subcommands in a group command, where ExecuteAll is True. To configure this, you must define these parameters in the top-level command and not in the individual subcommands. The dialog box applies to all of the subcommands.

Command Parameters

The following table describes the available command parameters. The value of the Macro column indicates whether macro expansion applies to the parameter. For more information about configuring the communications toolbar and Communications submenu commands, see Configuring User Interface Elements

Table Command Parameters

Parameter	Type	Macro	Description
AcceptReject	Boolean	Not applicable	Indicates whether the command is for prompting the agent to accept or reject a work item. Set to True for such a command. Execution of the device command is subject to the Accept or Reject dialog box and subject to the agent’s choices. If AcceptReject is True, then this dialog box displays, with the title specified by the ARTitle parameter. The work item matches the definition of the ARWorkItemID parameter: If the agent accepts the work item, then the device command for this command can be executed. If the agent rejects the work item, then the command specified by the AROnRejectCmd parameter is executed.
AllViews	Boolean	Not applicable	Parameter that, when set to False, disables the command on all views other than those specified using the View parameter. The default is True.
AROnRejectCmd	Char	Not applicable	Specifies the name of a command to be executed if the agent chooses to reject the work item. For example: AROnRejectCmd = "OnEmailWorkItemRejected"
ARTitle	Char	Not applicable	Provides text to be presented to the agent when the agent is prompted to accept or reject the work item. For example, for a command used for the accept or reject case for email work items, the parameter might be defined as follows: ARTitle = "Would You Like to Accept This Email Work Item?"
ARWorkItemID	Char	Yes	Defines the ID of the work item to be accepted or rejected. For example, the parameter might be defined as follows: ARWorkItemID = "{$InboundWorkItem(Email, WorkItemID)}"
CmdChannel OnFocus	Boolean	Not applicable	Specifies whether the command can only be enabled when the work item with the focus has the same channel as the device command for this command. In other words, if CmdChannelOnFocus is True, then the current work item is of a particular channel, and the device command is valid for a work item of this channel, then this command can be enabled. Otherwise, the command is disabled. For example, the command is disabled if all of the following are true: This parameter is set to True. The device command for this command is HoldCall (command is for Voice channel). The work item that currently has the focus (that is, the current item displayed in the Work Items list in the communications toolbar) is for a channel other than Voice. An equivalent way to filter the command is to define the FilterSpec parameter as follows: FilterSpec = [@SelectedWorkItem:ChannelType]='Voice'"
CmdData	Char	Not applicable	The command data definition name that describes parameter generation for this command to be passed to a device command (or to a business service method, for example). This parameter can be empty if the device command does not require any parameters from a command data parameters, or if no device command is specified. For more information, see Command Data. Note: Do not specify this parameter as a command parameter. Rather, specify a command data definition for the command directly, using the Administration - Communications screen. This parameter is used in DEF files that you export to or import from.
Description	Char	Yes	Description string for the command. This string appears in the ToolTip area when the user points to a communications toolbar button for this command. For more information, see About Communications Panel and Communications Toolbar Configuration and Configuring Communications Menu Commands.
DeviceCommand	Char	Not applicable	The device command executed when this communications command is executed. Device commands that are executed by the communications driver are specific to particular communications systems. Possible values include the device commands supported by your communications driver. Device commands based on special commands are not executed by a communications driver. For more information, see Special Commands for Device Commands.
ExecuteAll	Boolean	Not applicable	Default value is False. If you set ExecuteAll to True, then do not set ExecUntilOK to True. When used within a group command (containing subcommands), specifies that all subcommands can be executed. For example, if automatic login is in effect, and a default login command such as SignOnGroup is specified using the configuration parameter AutoLoginCmd, then all of this group command’s subcommands execute when the agent starts the Siebel session. In this example, the agent is logged in to all applicable communications systems, such as ACD queues. For more information, see Hierarchical Commands (Commands and Subcommands) and Configuring Communications Login and Logout.
ExecUntilOK	Boolean	Not applicable	Default value is False. If you set ExecUntilOK to True, then do not set ExecuteAll to True. When used within a group command (containing subcommands), specifies that each subcommand executes in sequence until one of them succeeds. If a subcommand fails to execute, then the next subcommand executes. For more information, see Hierarchical Commands (Commands and Subcommands).
FilterSpec	Char	Yes	Filter that supports simple or complex queries. Filter results are evaluated using a compound predicate that can include standard query operators to determine if the command matches. FilterSpec queries use standard comparison operators, including: = LIKE AND OR EXISTS > < >= <= Alternatively, FilterSpec can operate on the work item represented by the macro @SelectedWorkItem. For example, the following parameter definition matches voice work items: FilterSpec = "[@SelectedWorkItem:ChannelType]='Voice'" For more information, see the descriptions for the FilterSpec event handler parameter and the QuerySpec event response parameter.
Hidden	Boolean	Not applicable	Parameter that, when set to True, hides the command from the Communications submenu. This command is typically set to True for commands to appear only in the communications toolbar, or for commands that do not appear in the user interface. Set this parameter to False (the default) or omit the parameter in order for the command to appear in the Communications submenu. Use the Description, HotKey, MenuPosition, and Title parameters to specify additional settings relevant to the command’s appearance in the Communications submenu. For more information, see About Communications Panel and Communications Toolbar Configuration and Configuring Communications Menu Commands.
HotKey	Char	Not applicable	Keyboard shortcut to assign to this command, for use in the Communications submenu. This can be a combination of CTRL, ALT, or SHIFT and one of the keyboard letter or function keys, or just a single letter or function key. For example, valid values for the HotKey parameter include F12, CTRL+SHIFT+F, and so on. Keyboard shortcuts defined for communications commands do not use as input any data entered into the text entry field in the communications toolbar. Note: If you specify keyboard shortcuts, using the HotKey parameter, that conflict with keyboard shortcuts (accelerators) specified for commands in Siebel Tools, then the shortcuts for Siebel Tools take precedence over shortcuts assigned to this command by using the HotKey parameter. For more information, see Configuring Communications Menu Commands.
HotKeyText	Char	Not applicable	Specifies locale-dependent text to represent the keyboard accelerator for the command’s menu item. The keyboard accelerator itself is specified using the HotKey parameter. This locale-dependent text appears in the Communications submenu. If HotKeyText is not used, then the text specified in HotKey is used instead. For more information, see Configuring Communications Menu Commands.
IndicateActiveCmd	Boolean	Not applicable	Parameter that, when set to True, specifies whether the toolbar button for this command must display the correct channel-specific icon for the device command for the active subcommand. This parameter is used in group commands containing subcommands for multiple channels, such as the AcceptWorkGroup command, for the Accept Work Item toolbar button. The default is False.
LocalMenu	Boolean	Not applicable	Parameter that, when set to True, enables this command so it appears in the context-sensitive applet-level menu. This feature lets you, for example, define an applet-level menu item called Call Contact that is available when an agent works with contact records. The default is False. For more information, see Configuring Communications Menu Commands.
MenuPosition	Char	Not applicable	Parameter setting that determines the order in which the command appears in the Communications submenu or in the applet-level menu. Commands appear in ascending order with respect to the MenuPosition values: those with lower MenuPosition values appear first followed by those with higher MenuPosition values. Values for the MenuPosition parameter can also specify additional menu command levels, within the Communications submenu of the Tools application-level menu. The applet-level menu commands, however, are all on a single level. For example, assume the SignOnGroupInMenu command (with Title parameter value Log In) has a MenuPosition value of 20. This group command appears in the Communications submenu, after any items with lower number, and in turn has subcommands representing submenu items. The subcommand LoginToPBX has values of 20.1, 20.2, and 20.3, specifying that it appears as a submenu item to SignOnGroupInMenu. LoginToPBX, with Title parameter value Log In (Phone), would be available to agents at the following path in the application-level menu: Tools, then Communications, then Log In, then Log In (Phone) For more information, see Configuring Communications Menu Commands.
OnEditControl	Boolean	Not applicable	Parameter that, when set to True, means that the command requires that the edit field in the communications toolbar has the focus and contains data. The default is False.
Profile	Char	Not applicable	Name of the communications driver profile that supports the device command associated with this command. If a profile is associated with the command, then the command can only be sent to the communications driver for that profile. For more information, see Creating Commands. Note: Do not specify this parameter as a command parameter. Rather, specify the profile for the command directly, using the Administration - Communications screen. This parameter is used in DEF files that you export to or import from.
Script	Char	Not applicable	Siebel VB or Siebel eScript script name to invoke (if specified). Parameters are passed using the ScriptParam parameter for the associated command data definition. For more information about using Siebel VB or Siebel eScript, see Integrating with Siebel Scripting Languages.
ServiceMethod	Char	Not applicable	The name of a Siebel business service and method to be called. The service and method are specified in the form service.method. Optionally, you can use the ServiceParam parameter for the associated command data definition to provide parameter names and values to pass to the method to be called. For more information, see Using Business Services with Siebel Communications Server.
SubCommand_N	Multi	Not applicable	The name of a command that is specified as a subcommand for the current command. The commands might appear to an agent as one command because only one of them is active at any point, depending on the Siebel context and the specified Order values for the subcommands. Alternatively, all subcommands can execute, if the ExecuteAll parameter is set to True. In a DEF file (the only place this parameter appears), the suffix N represents the order value for the subcommand. For example, a call-transfer command might be either to transfer to an employee or to transfer to a service request owner, depending on the current business component. The commands that are invoked from the communications toolbar and the Communications submenu often invoke other commands, which are specified as subcommands. Note: Do not specify this parameter as a command parameter. Rather, specify subcommands for the command directly, using the Administration - Communications screen. This parameter is used in DEF files that you export to or import from.
Title	Char	Not applicable	Name of the Communications submenu item associated with this command. If no Title parameter is specified, then the name of the device command serves as the menu item name. For more information, see Configuring Communications Menu Commands.
View	Multi	Not applicable	Names of the views where this command is enabled if the AllViews parameter value is False.

Command Data

This topic describes command data.

Command data definitions in the communications configuration data define how communications command parameters are generated for use with a corresponding command. For example, a command data definition can instruct one of the transfer commands to transfer the caller to the current service request owner or can display a specified Siebel view and extract the transfer destination from that view.

Command Data Parameters

The following table describes the parameters available in command data definitions. The value of the Macro column indicates whether macro expansion applies to the parameter.

Table Command Data Parameters

Parameter	Type	Macro	Description
AttachContext	Boolean	Not applicable	Parameter that, when set to True, allows automatic passing of current screen-context data with the current work item. This is the easiest way of transferring screens between agents. AttachContext applies to voice work items only. The default is False. The Send Screen Pop and Receive Screen Pop settings in the Communications options of the User Preferences screen override the setting of the AttachContext command parameter. For more information, see Setting Communications User Preferences. Note: The size of a Siebel screen bookmark is defined by the middleware and communications driver and might vary according to each vendor.
BusComp	Char	Not applicable	Business component name. If this parameter is empty, then the associated command is enabled on all views. If a business component name is specified, then the associated command is enabled only on views that are based on the specified business component.
BusObj	Char	Not applicable	Business object name. If this parameter is empty, then the associated command is enabled on all views. If a business object name is specified, then the associated command is enabled only on views that are based on the specified business object.
OnField	Char	Not applicable	Field name that is required to be active. If this property is specified, then the related command is enabled only when this field is active (that is, when a cursor is in this field).
Param	Group	Yes	Parameter names and values for the command. You can use this parameter to pass data to accompany the device command, whether for a communications driver or a special command. You create each parameter that you need in the form Param.param_name, then specify a value for the parameter that you pass for the device command. Parameters are specific to commands for particular middleware vendors, and possible values for these parameters depend on the communications driver. Example syntax follows for a subparameter CmdParamName and an event field named EventFieldName. This parameter value can be used to fetch event data defined as a child property set. Param.CmdParamName = {EventFields.EventFieldName} The Param parameter can also be used to pass parameter values received from outside Communications Server, such as from a business service that invokes a Siebel communications command. For more information, see About Using Business Services with Events and Commands.
RequiredField	Group	Yes	Field name and filter pair that are used as a criterion to determine if this command is active for this condition. RequiredField is always based on the currently selected row. For example, the following property causes the specified command to be disabled if field A of the current (selected) row in the current (active) applet does not contain a value that ends with X2. RequiredField.A = "*X2"
ScriptParam	Group	Yes	A group of subparameters that are parameters to the script method (if any) invoked using the Script parameter. You create each parameter that you need in the form ScriptParam.param_name, then specify a parameter value that is passed to the script. The parameter names themselves are not passed to the script. Order parameters in the sequence in which they are expected by the script: ScriptParam.Param1 = "value1" ScriptParam.Param2 = "name" Param1 and Param2 are subparameters of the ScriptParam parameter.
SelectApplet	Char	Not applicable	An applet from which an agent can make a selection, such as to select a recipient for a work item or to specify a reason code. You can specify the following applets: Accept Reject Popup Applet ACD Transfer Call Applet Transfer Multiple LOV Popup Applet
SelectBusComp	Char	Not applicable	Business component for an applet from which an agent can make a selection.
SelectBusObj	Char	Not applicable	Business object specifying application elements from which an agent can make a selection.
SelectParam	Boolean	Not applicable	Parameter that, when set to True, enables an applet in which the user can make a selection. For example, the applet can be used to select the person to whom to send, transfer, or conference a work item (such as to call or to transfer a call to) or used to specify a reason code. For example, for a MakeCall command, a dialog box can be displayed from which the agent can select an employee to call. The SelectBusObj, SelectBusComp, SelectApplet, SelectTitle, and SelectQuerySpec parameters determine the specific nature of the selection applet. The default is False.
SelectQuerySpec	Char	Yes	A query specification for an applet, such as Transfer Multiple LOV Popup Applet, from which an agent can make a selection. For example, a command data definition can use SelectQuerySpec as follows: [CmdData:NotReadyWithPopup] SelectParam = "True" SelectTitle = "Select the reason for changing status to Not Ready" SelectApplet = "Transfer Multiple LOV Popup Applet" SelectBusObj = "List Of Values" SelectBusComp = "List Of Values" SelectQuerySpec = "[Type]='REASON_CODE' AND [Active] = 'Y'" Param.Reason = "[Value]" In this example, SelectQuerySpec queries the List of Values business component to obtain the values to display in the Reason Codes list. If the applet allows you to select multiple records, as does Transfer Multiple LOV Popup Applet, then the selection values are concatenated as comma-separated values.
SelectTitle	Char	Not applicable	The title for the applet (dialog box) from which an agent can select a recipient for a work item. If this value is not specified, then the applet has the title that is assigned to the selection applet.
ServiceParam	Group	Yes	A group of subparameters that are parameters to the Siebel business service method (if any) invoked using the ServiceMethod parameter for the associated command. You create each parameter that you need in the form ServiceParam.param_name, then specify a parameter value. The parameter name and value are both passed to the service method. Order parameters in the sequence in which they are expected by the service method: ServiceParam.Param1 = "value1" ServiceParam.Param2 = "name" Param1 and Param2 are subparameters of the ServiceParam parameter. For more information, see Using Business Services with Siebel Communications Server.
WorkTrackingObj	Group	Yes	Field name and values of a work-tracking object previously specified in an event log definition. The WorkTrackingObj command data parameter stores or updates this object for the currently selected work item. For example, the following command and command data definitions update the customer dashboard with a contact ID: [Command:UpdateDashboardFromContact] Hidden = "True" ServiceMethod = "Persistent Customer Dashboard.Update Dashboard from CTI" CmdData = "UpdateDashboardFromContact" [CmdData:UpdateDashboardFromContact] BusComp = "Contact" ServiceParam.Field = "Id" ServiceParam.Value = "{Id}" WorkTrackingObj.ContactId = "{Id}" The WorkTrackingObj parameter updates the attribute value of "ContactId" for the currently selected work item. In this example, ContactId is a custom work item attribute. You can also use WorkTrackingObj to update the Siebel bookmark. For example, using the following line in a command data definition for a command to resume a suspended work item (such as to remove a call from hold) prevents a screen pop from occurring when an agent resumes a work item. If this parameter is not defined as shown, then a screen pop might display the view the agent was on when the work item was suspended. WorkTrackingObj.ViewBookmark = "" For more information, see Work Item Attributes.