Sheet Configuration

Sheets can be defined under Services ‣ CTI Server ‣ Models in the web interface. Once a sheet is defined, it has to be assigned to an event in the Services ‣ CTI Server ‣ Events menu.

Model
The model contains the content of the displayed sheet.
Event
Events are actions that trigger the defined sheet. A sheet can be assigned to many events. In that case, the sheet will be raised for each event.
../../_images/sheets_configuration.png

General settings

../../_images/sheets_configuration_general.png

You must give a name to your sheet to be able to select it later.

The Focus checkbox makes the XiVO Client pop up when the sheet is displayed, if the XiVO Client was hidden.

Sheets

There are two different ways to configure the contents of the sheet:

  • creating a custom sheet from the Qt designer. This gives you a total control on the layout of the information and allows you to save and process data entered during or after a call.
  • listing the different fields and their content. The information will be automatically laid out in a linear fashion and will be read-only.

Custom sheet

Configuring the sheet

../../_images/sheets_configuration_sheet_custom.png

The Qt interface field is the path to the UI file created by the Qt Designer. The path can either be a local file on your XiVO starting with file://, or a HTTP URL. When using a local file, make sure that the system user xivo-ctid has read access to the file.

You must add a field with type form and display value qtui for the form to be displayed.

Create a custom sheet with Qt Designer

The Qt Designer is part of the Qt development kit and is also available in the Qt Creator. They are available on the Qt project website.

Here is an example of a small form created with Qt Designer.

../../_images/sheets_configuration_qtui.png

The Qt Designer screenshot.

../../_images/sheets_configuration_qtdesigner.png

Warning

In Qt Designer, one must set ‘vertical layout’ on the top widget (right click on the top widget > Lay out > Vertical layout).

You can download the file generated by this example from Qt Designer: example-form.ui

Text fields (QLineEdit, QLabel, QPlainTextEdit) can contain variables that will be substituted. See the variable list for more information.

List of fields

Default XiVO sheet example :

../../_images/sheets_configuration_sheet.png

Example showing all kinds of fields:

../../_images/sheets_configuration_sheet_demo.png

Each field is represented by the following parameters :

  • Field title : name of your line used as label on the sheet.
  • Field type : define the type of field displayed on the sheet. Supported field types :
    • title : to create a title on your sheet
    • text : show a text
    • url : a simple url link, open your default browser.
    • urlx : an url button
    • phone : create a tel: link, you can click to call on your sheet.
    • form : show the form from an ui predefined. It’s an xml ui. You need to define qtui in display format.
  • Default value : if given, this value will be used when all substitutions in the display value field fail.
  • Display value : you can define text, variables or both. See the variable list for more information.

Variables

Three kinds of variables are available :

  • xivo- prefix is reserved and set inside the CTI server:
    • xivo-where for sheet events, event triggering the sheet
    • xivo-origin place from where the lookup is requested (did, internal, forcelookup)
    • xivo-direction incoming or internal
    • xivo-did DID number
    • xivo-calleridnum
    • xivo-calleridname
    • xivo-calleridrdnis contains information whether there was a transfer
    • xivo-calleridton Type Of Network (national, international)
    • xivo-calledidnum
    • xivo-calledidname
    • xivo-ipbxid (xivo-astid in 1.1)
    • xivo-directory : for directory requests, it is the directory database the item has been found
    • xivo-queuename queue called
    • xivo-agentnumber agent number called
    • xivo-date formatted date string
    • xivo-time formatted time string, when the sheet was triggered
    • xivo-channel asterisk channel value (for advanced users)
    • xivo-uniqueid asterisk uniqueid value (for advanced users)
  • db- prefixed variables are defined when the reverse lookup returns a result.

For example if you want to access to the reverse lookup full name, you need to define a field fullname in the directory definition, mapping to the full name field in your directory. The {db-fullname} will be replaced by the caller full name. Every field of the directory is accessible this way.

  • dp- prefixed ones are the variables set through the dialplan (through UserEvent application)

For example if you want to access from the dialplan to a variable dp-test you need to add in your dialplan this line (in a subroutine):

UserEvent(dialplan2cti,UNIQUEID: ${UNIQUEID},CHANNEL: ${CHANNEL},VARIABLE: test,VALUE: "Salut")

The {dp-test} displays Salut.

Sending informations during/after a call

After showing a sheet, the XiVO Client can also send back information to XiVO for post-processing or archiving.

Here are the requirements:

  • The sheet must contain a button named save to submit information
  • Supported widgets:
    • QCalendarWidget
    • QCheckBox
    • QComboBox
    • QDateEdit
    • QDateTime
    • QDateTimeEdit
    • QDoubleSpinBox
    • QLabel
    • QLineEdit
    • QList
    • QPlainTextEdit
    • QRadioButton
    • QSpinBox
    • QTimeEdit
  • Fields must have their name starting with XIVOFORM_

If you want to send information that is not visible, you can make the widget invisible on the sheet:

  • change the maximumWidth or maximumHeight property to 0

  • edit the .ui file and add the following property to the widget:

    <property name="visible">
      <bool>false</bool>
    </property>
    

When a CTI client submits a custom sheet, a call_form_result event is published on the event bus.

Systray

Mostly the same syntax as the sheet with less field types available (title, body). A Systray popup will display a single title (the last one added to the list of fields) and zero, one or more fields of type ‘body’.

../../_images/sheets_configuration_systray.png

Warning

The popup message on MacOSX works with Growl http://growl.info. We could get simple sheet popup to work using the free Growl Fork http://www.macupdate.com/app/mac/41038/growl-fork Note that this is not officially supported.

Actions

The action is for the xivo client, so if you configure an action, please be sure you understand it’s executed by the client. You need to allow this action in the client configuration too (menu XiVO Client -> Configure, tab Functions, tick option Customer Info and in sub-tab Customer Info tick the option Allow the Automatic Opening of URL).

The field in this tab receives the URL that will be displayed in your browser. You can also use variable substitution in this field.

  • http://example.org/foo opens the URL on the default browser
  • http://example.org/{xivo-did} opens the URL on the default browser, after substituting the {xivo-did} variable. If the substitution fails, the URL will remain http://example.org/{xivo-did}, i.e. the curly brackets will still be present.
  • http://example.org/{xivo-did}?origin={xivo-origin} opens the URL on the default browser, after substituting the variables. If at least one of the substitution is successful, the failing substitutions will be replaced by an empty string. For example, if {xivo-origin} is replaced by ‘outcall’ but {xivo-did} is not substituted, the resulting URL will be http://example.org/?origin=outcall
  • tcp://x.y.z.co.fr:4545/?var1=a1&var2=a2 connects to TCP port 4545 on x.y.z.co.fr, sends the string var1=a1&var2=a2, then closes
  • udp://x.y.z.co.fr:4545/?var1=a1&var2=a2 connects to UDP port 4545 on x.y.z.co.fr, sends the string var1=a1&var2=a2, then closes

Note

any string that would not be understood as an URL will be handled like and URL it is a process to launch and will be executed as it is written

For tcp:// and udp://, it is a requirement that the string between / and ? is empty. An extension could be to define other serialization methods, if needed.

../../_images/sheets_configuration_actions.png

Event configuration

You can configure a sheet when a specific event is called. For example if you want to receive a sheet when an agent answers to a call, you can choose a sheet model for the Link event.

The following events are available :

  • Dial: When the member’s phone starts ringing for calls on a group or queue or when the user receives a call
  • Link: When a user or agent answers a call
  • Unlink: When a user or agent hangup a call received from a queue
  • Incoming DID: Received a call in a DID
  • Hangup: Hangup the call
../../_images/events_configuration.png