Siebel CTI Administration Guide > Configuring Advanced Communications Features > Using Macro Expansion for Character Fields >

Macros for Parameter Values

Several macros (sometimes referred to as special fields) can be used within values for applicable event or command parameters, configuration parameters, or, in limited cases, driver parameters.

NOTE:  Unless otherwise stated, you cannot use the macros described in this topic within values for communications driver parameters.

When the parameter value is read into memory (such as when the event or command is invoked), particular values are substituted for the macro name. These macros are not specific to any particular communications system, such as a specific CTI middleware product.

Some macros require work item attributes to be provided. Notations for specifying attributes are shown in examples. For more information, see Work Item Attributes.

Event attributes are also available for use in parameter values that support macro expansion. For example, the event attribute SiebelChannelType represents the channel type of the current work item. For more information, see Driver Event Attributes.

The macros that start with the at sign (@) are static variables with values that are defined at run time (values for some of these macros might change during a user session). The macros that start with the dollar sign ($) are actually functions that return a value. The macros, which have names that start with the at sign (@) or the dollar sign ($), are listed as follows:

• @ACDDNList. The list of ACD DNs (extensions of type A) associated with the current agent.

  The values are separated by commas.

• @AgentId. Agent login for the current agent.
• @AgentPin. Password for the agent login for the current agent.
• @ClientHostName. Host name of the agent's computer. You can use this macro with hoteling implementations using the Virtual CTI driver. For more information, see Using the Virtual CTI Driver.
• @ClientIP. IP address of the agent's computer. You can use this macro with hoteling implementations using the Virtual CTI driver. For more information, see Using the Virtual CTI Driver.
• @Configuration. The current configuration for the agent.
• @CountryCode. The country code applicable to the agent's location.

  If the agent's country is the U.S., then this macro returns an empty value. If the agent's country is other than the U.S., then the macro returns the applicable country code, preceded by a plus (+). For example, if the agent's country is France, then the macro returns +33.

• @DeselectedWorkItem. The item in the Work Items list in the communications toolbar that had the focus just prior to the item that currently has the focus. (The item with the focus is represented by the @SelectedWorkItem macro.) This macro must be specified with an attribute value, as follows:

  @DeselectedWorkItem:attribute_name

  where attribute_name is the work item attribute you are providing. For more information, see Work Item Attributes.

• $DialingRuleMethod. Used within parameter values for the DialingFilter.RuleN configuration parameters, this macro calls a custom business service method to determine how to translate phone numbers when the dialing filter is in effect.

  The custom business service must recognize the input arguments Filter and PhoneNumber. Filter is the filter in effect for the parameter that invokes the macro. PhoneNumber is the number that needs to be translated. For example, for the following dialing rule, Filter is 650:

  DialingFilter.Rule2 = "650->$DialingRuleMethod(myservice.mymethod)"

  The business service must also support an output parameter called PhoneNumber. For example, if your dialing filter rule is to be applied to the U.S. number (650) 123-4567, where numbers with prefix 123 in the area code (650) must be changed to use prefix 555, then the business service method might return the PhoneNumber output parameter with the value 916505554567.

  After a dialing filter rule is applied that uses the macro $DialingRuleMethod, no other filters are applied.

  For more information about using this macro with dialing filters, see Working with Dialing Filters.

• @DNList. The list of DNs (standard extensions of type S) associated with the current agent.

  The values are separated by commas.

• @EditControl. The data in the edit field (text box) control in the communications toolbar.

  This macro yields a value only when the edit field in the communications toolbar has the focus and contains a value. Use @EditControl when agents input values other than phone numbers into the communications toolbar's edit field, such as to log in to the switch.

• $GetCommandStatus. Obtains the status of the device command for a communications command. Possible status values returned are:
  • Checked. The command is in toggled-down state, and the button displays (for example, if the agent indicates Not Ready for new work items, then the button is toggled down).
  • Blinking. The command is available, and the button is blinking.
  • Enabled. The command is available, and the button is enabled.

    NOTE:  You can use this macro within command parameters, but not within event parameters. Events cannot use this macro to determine the status of a device command.

  • Disabled. The command is not available, and the button is disabled.

    You can obtain the command status with an expression like this:

    $GetCommandStatus(device_command)

    where device_command is the name of the device command for the command. For example, a command parameter to determine the status of the device command might be defined as follows:

    FilterSpec = "[$GetCommandStatus(ChangeNotReadyState)]='Checked'"

    In this case, if the status of ChangeNotReadyState is Checked, then FilterSpec matches, and the command containing this FilterSpec parameter can execute.

• $GetInboundWorkItemAttr. Obtains the attributes of an inbound work item.

  You can obtain the work item attributes with an expression like this:

  $GetInboundWorkItemAttr(channel_name, attribute_name)

  where channel_name is the name of the locale-independent channel for the work item, and attribute_name is the work item attribute you are interested in. For example, a command data parameter to obtain the tracking ID of an inbound voice work item might be defined as follows:

  Param.TrackID = "{$GetInboundWorkItemAttr(Voice, DriverWorkTrackID)}"

  For more information, see Work Item Attributes.

• $GetWorkItemAttr. Obtains the attributes of a work item, for example, in an event handler evaluating a new work item, or in a command.

  You can obtain the work item attributes with an expression like this:

  $GetWorkItemAttr(workitem_ID, attribute_name)

  where workitem_ID is the ID number of the work item, if known, and attribute_name is the work item attribute you are interested in.

  For example, an event handler parameter to verify that the ContactId attribute (a custom work item attribute) has a value might be defined as follows:

  FilterSpec = "[$GetWorkItemAttr(SiebelWorkItemID, ContactId)] IS NOT NULL"

  For commands operating on the selected work item, you can also obtain work item attributes using @SelectedWorkItem:attribute_name.

  For more information, see Work Item Attributes. For more information about the SiebelWorkItemID attribute, see Driver Event Attributes.

• $HotelingPhone. Retrieves an agent's extension if the agent is using a hoteling teleset. The field value is calculated at run time according to these rules:
  • Uses the login name of the currently selected agent (employee), or the name of a service request owner, to find the agent's run-time extension, if the agent is using a hoteling teleset. In the first example following, Login Name is the Login Name field of the current business component, which corresponds to the LOGIN column in the S_USER table.
  • If the extension is not found, then $HotelingPhone retrieves the employee's extension number from the S_USER table.

    The following example parameter definition in a make-call command (command data definition) might generate the extension you want, based on the Login Name field:

    Param.PhoneNumber = "{$HotelingPhone(Login Name):Lookup}"

    Alternatively, the following example parameter definition for a make-call command might generate the extension you want, based on the Owner field. Use a parameter value like this for a command invoked when the current business component is Service Request, to call the owner of the current service request record.

    Param.PhoneNumber = "{$HotelingPhone(Owner):Lookup}"

    For more information, see Configuring Telesets for Hoteling.

    NOTE:  For a deployment using the Virtual CTI driver, this topic does not apply. However, you can implement hoteling using this driver. For more information, see Using the Virtual CTI Driver.

    NOTE:  The macro @HotelingPhone is still supported, for compatibility with release 6.x, but it is recommended that you use $HotelingPhone instead.

• @Language. The language code applicable to the agent's Siebel application session. For example, the language code for U.S. English is ENU.
• @Now. Returns the current timestamp, using the following format:

  %month/%day/%Year %H:%M:%S

• @Phone. Represents a phone number, whose value is calculated at run time according to these rules:
  • If the Phone # field in the communications toolbar has the focus and contains a value, then @Phone is equal to the value of this field.
  • If the Phone # field has no value, but the currently active applet field is of the type DTYPE_PHONE, then @Phone is equal to the value of this field.
  • If the Phone # field has no value and the currently active field is not of the type DTYPE_PHONE, then @Phone is equal to the value of the field referred to by the Primary Phone Field user property for the business component.

    In all other cases, the @Phone macro contains no data. For more information, see Macro Expansion with Phone Numbers.

• @PrimaryQueueList. The list of ACD queues associated with the agent and designated as primary. For example, a login command might include a parameter like this to identify which ACD queues to log the agent into:

  Param.ACDQueue = "{@PrimaryQueueList}"

  The values are separated by commas.

• @QueueId. The list of ACD queues associated with the agent and designated as primary.

  NOTE:  @PrimaryQueueList replaces @QueueId, but you can still use @QueueId for compatibility purposes.

• @QueueList. The list of ACD queues associated with the agent. This list includes all such queues, including those marked as primary and those not marked as primary. The values are separated by commas.
• @Random. A string containing 10 random digits. You can use this macro for testing purposes.
• $RemoteConnectStr. The name of the remote call center. This macro, which you can use with transfers and conference calls between call centers, derives the name of a remote call center's communications configuration from either:
  • The ConnectString configuration parameter (if defined), or
  • The extension number of the agent to be called

    For example, a command parameter in a transfer or conference command might generate the configuration name in this fashion:

    Param.RemoteConnectStr = "[$RemoteConnectStr(@Phone)]"

    For more information, see Configuring Remote Transfers and Conferences.

• $RemoteConnectStr2. The name of the remote call center. This macro, which you can use with transfers and conference calls between call centers, derives the name of a remote call center's communications configuration from either:
  • The ConnectString configuration parameter (if defined), or
  • The employee ID of the agent to be called

    For example, where the SelectBusObj and SelectBusComp parameters are set to Employee, a command parameter in a transfer or conference command might generate the configuration name in this fashion:

    Param.RemoteConnectStr = "[$RemoteConnectStr2(Id)]"

    The Employee business component uses the Id field to uniquely identify an employee record. A command that references another business component might have to use another field name to uniquely identify a record. For more information, see Configuring Remote Transfers and Conferences.

• @SelectedDN. The currently selected extension in the Communications options of the User Preferences screen.
• @SelectedQueue. The currently selected ACD queue record in the Agent Queues list in the Communications options of the User Preferences screen.
• @SelectedText. Text the user has selected in the browser, such as in a field in an applet within the Siebel application. The text might be used, for example, to provide a phone number to call or to provide some other input data for a command.
• @SelectedWorkItem. The item in the Work Items list in the communications toolbar that has the focus. (The item that had the focus just prior to this item is represented by the @DeselectedWorkItem macro.) This macro must be specified with an attribute value, as follows:

  @SelectedWorkItem:attribute_name

  where attribute_name is the work item attribute you are providing. For more information, see Work Item Attributes.

• @UserId. Siebel login ID of the current Siebel user.
• @UserName. Login name of the current Siebel user.
• @UIPhone. The phone number that the agent clicked. See also the description of the communications parameter CallFromUICommand, in Parameters for Communications Configurations.
• @WorkDuration. Length of time, in seconds, of the current work item. That is, the time elapsed since the work item started.
• @WorkObjectID. Row ID of the work-item tracking object that was transferred to the agent or that was created as a result of creating an event log and defining a value for the AfterWork event log parameter.
• @WorkStartTime. Date and time (timestamp) when the work item arrived or was initiated. The timestamp is in the following format:

  %month/%day/%year %H:%M:%S

@Phone Macro Example

The example command and associated command data shown in Table 23 and Table 24 use the @Phone macro, which you can use to dial any phone field on any business component.

Table 24 shows a command data definition for this command definition.