SoftPhone XML Format Reference
A CTI connector maintains an XML representation of the SoftPhone user interface according to the following XML format. It is this XML that is transmitted to the SoftPhone connector through the CTI connector's UIRefresh event.
The following diagram shows the relationship between each element in the SoftPhone XML format. Elements in italic bold are broken out separately below the main diagram:
The sections that follow include descriptions of each element, as organized by parent. Italicized elements are broken out separately in their own section:
CTIUserInterface on page 63 • CTIAgent on page 64 • CTIAgentState on page 64 • CTICallLog on page 73 • CTIElementSet on page 67 • CTIForm on page 65 • CTIInteractiveControlContainer on page 75 • CTILine on page 65 • CTIElementSet on page 67 • CTILineOnlyElementSet on page 78 • CTILogo on page 66 • CTIPreviousCalls on page 66 • CTICallLog on page 73
• CTIReasonCodeSet on page 67 • CTIReasonCode on page 67 CTIElementSet on page 67 • CTIInteractiveControlContainer on page 75 • CTITimer on page 68 • CTIStaticText on page 68 • CTIProgressBar on page 69 • CTILink on page 73 • CTIParty on page 69 • CTIProgressBar on page 69 • CTIInfoField on page 71 • CTIRelatedObjectSet on page 71 • CTIRelatedObject on page 72 • CTIField on page 72 CTICallLog on page 73 • CTIComments on page 74 • CTIWho on page 74 • CTIWhat on page 74 CTIInteractiveControlContainer on page 75 • CTIButton on page 75 • CTIEditBox on page 76 • CTICheckBox on page 77 • CTIComboBox on page 77 • CTIComboBoxValue on page 77 CTILineOnlyElementSet on page 78 • CTIDialPad on page 78 • CTIComments on page 74
CTIUserInterface
This element encapsulates the entire SoftPhone. Properties
content=complex Children
CTIAgent,CTILine,CTIStaticText,CTIProgressBar,CTILink,CTIParty,CTITimer,CTIEditBox, CTIComboBox,CTICheckbox,CTIButton,CTIForm,CTIReasonCodeSet,CTICallLog,
CTIPreviousCalls,CTILogo
CTIAgent
This element encapsulates the call center state section of the SoftPhone interface. If this section is left blank, then no call center state picklist or icon is displayed.
Properties
isRef=0; minOcc=0; maxOcc=1; content=complex Parent CTIUserInterface Children CTIAgentState Attributes Description Required? Type Attribute Name
Specifies your own image for the call center state section of the SoftPhone. Salesforce.com recommends Optional
String ICON_URL
that you store the image as an externally available document in the Documents tab for your organization. For information on how to create an externally available document, see "Uploading and Replacing Documents" in the Salesforce online help. For information on how to determine the URL of an image that is stored in the Documents tab, see Adding a Custom Logo on page 43.
CTIAgentState
This element encapsulates a call center state that is available in the call center state picklist (for example, Not Ready for Calls). If the SELECTED attribute of a call center state is set to True, this is the state that is currently active.
Properties
isRef=0; minOcc=0; maxOcc=unbounded; content=complex Parent CTIAgent Attributes Description Required? Type Attribute Name
If set to True, this call center state value is displayed as currently active. The default value for this attribute is False.
Optional String
SELECTED
The order in which this call center state is displayed in the call center state picklist. States are displayed in ascending order according to their ORDER attributes. Integer
ORDER
Identifies the call center state within the CTI adapter code
Required String
ID
Specifies the text that is used for the call center state in the SoftPhone
Optional String
LABEL
CTIForm
This element encapsulates a set of controls in the SoftPhone user interface that allows a user to specify data. When a button in the form is clicked, the data contained in the form is sent to the SoftPhone CTI adapter on the query string of the button command.
Properties
isRef=0; minOcc=0; maxOcc=unbounded; content=complex Parent
CTIUserInterface Children
CTIEditBox,CTIComboBox,CTICheckbox,CTIButton
CTILine
This element encapsulates a single phone line in the SoftPhone user interface. Properties
isRef=0; minOcc=0; maxOcc=unbounded; content=complex Parent
CTIUserInterface Children
CTIStaticText,CTIProgressBar,CTILink,CTIParty,CTITimer,CTIEditBox,CTIComboBox, CTICheckbox,CTIButton,CTIButton,CTIDialpad,CTIComments
Attributes
Description Required?
Type Attribute Name
Specifies the sequential number that identifies the line in the SoftPhone. For example, line 1, line 2, line 3, and so on.
Required Positive
Integer LINE_NUMBER
Specifies the current status of the line. Possible values include Open, Ringing, and Busy.
Required String
STATE
Specifies the unique ID of the call that this line contains. If the line does not contain a call, this value can remain unspecified.
Optional String
CALL_OBJECT_ID
Specifies the extension number that is associated with the phone line.
Optional String
EXTENSION
If set to True, the name of this line (for example, "Line 1") is displayed as a link, which, when clicked, sets the Optional
Boolean ALLOW_ALTERNATE
line as the currently active line. This attribute should not be set to True when ALLOW_DIAL_PAD is set to
True.
If set to True, the name of this line (for example, "Line 1") is displayed as a link, which, when clicked, shows Optional
Boolean ALLOW_DIAL_PAD
the dial pad for the line. This attribute should not be set to True when ALLOW_ALTERNATE is set to True.
CTILogo
This element encapsulates the logo section at the bottom of the SoftPhone. Properties
isRef=0; minOcc=0; maxOcc=1; content=complex Parent CTIUserInterface Attributes Description Required? Type Attribute Name
Specifies the URL of your own logo image. Logos should be exactly 116 pixels wide by 31 pixels high. Required
String IMAGE_URL
Salesforce.com recommends that you store the image as an externally available document in the Documents tab for your organization. For information on how to create an externally available document, see "Uploading and Replacing Documents" in the Salesforce online help. For information on how to determine the URL of an image that is stored in the Documents tab, see Adding a Custom Logo on page 43.
If specified, this value places a link at the top left corner of the logo area with the label that is specified in Optional
String LINK_URL
LINK_TEXT. If you specify a URL, you should also
specify values for LINK_TEXT, WINDOW_WIDTH, and WINDOW_HEIGHT.
The label at the top left corner of the logo area that links to the URL that is specified in LINK_URL
Optional String
LINK_TEXT
The width, in pixels, of the popup window that displays when the link specified by LINK_URL and LINK_TEXT is clicked
Optional Integer
WINDOW_WIDTH
The height, in pixels, of the popup window that displays when the link specified by LINK_URL and LINK_TEXT is clicked
Optional Integer
WINDOW_HEIGHT
CTIPreviousCalls
This element encapsulates a group of logs for calls that have been completed. Properties
isRef=0; minOcc=0; maxOcc=1; content=complex Parent
CTIUserInterface Children
CTICallLog
Attributes
Description Required?
Type Attribute Name
If set to True, the collapsible list of previous call logs should be displayed in its open state
Required Boolean
OPEN
CTIReasonCodeSet
This element encapsulates a set of reason codes in the SoftPhone user interface. Some organizations might require users to choose a reason code from a reason code set when the user wants to end a call, enter the Not Ready for Calls state, or log out. Properties
isRef=0; minOcc=0; maxOcc=1; content=complex Parent CTIUserInterface Children CTIReasonCode Attributes Description Required? Type Attribute Name
Identifies the reason code set within the CTI adapter code
Required String
ID
Specifies the text that is used for the reason code set in the SoftPhone
Optional String
LABEL
CTIReasonCode
This element encapsulates a single reason code in the SoftPhone user interface. Some organizations might require users to choose a reason code from a reason code set when the user wants to end a call, enter the Not Ready for Calls state, or log out. Properties
isRef=0; minOcc=0; maxOcc=unbounded; content=complex Parent CTIReasonCodeSet Attributes Description Required? Type Attribute Name
Identifies the reason code within the CTI adapter code Required
String ID
Specifies the text that is used for the reason code in the SoftPhone
Optional String
LABEL
CTIElementSet
This group is comprised of the set of available elements that can exist in the SoftPhone.
Parents
CTIUserInterface,CTILine Children
CTIStaticText,CTIProgressBar,CTILink,CTIParty,CTITimer,CTIEditBox,CTIComboBox, CTICheckbox,CTIButton
CTIStaticText
This element represents an read-only text field. Properties
isRef=0; minOcc=0; maxOcc=unbounded; content=complex Parent CTIElementSet Attributes Description Required? Type Attribute Name
Specifies the developer name for the static text Required
String ID
Specifies the text to use for the static text in the SoftPhone
Optional String
LABEL
If set to True, this static text displays in red. Optional
Boolean ERROR
CTITimer
This element represents a clock that counts the number of seconds and minutes that have passed since a particular moment. For example, a timer can be used to track a call's duration, or the amount of time a caller has been on hold.
Properties
isRef=0; minOcc=0; maxOcc=unbounded; content=complex Parent CTIElementSet Attributes Description Required? Type Attribute Name
Specifies the name of the timer within the CTI adapter code
Required String
ID
Specifies the text that is used for the timer in the SoftPhone
Optional String
LABEL
Specifies the starting value that should be displayed for the number of minutes
Optional Integer
MINUTES
Specifies the starting value that should be displayed for the number of seconds
Optional Integer
SECONDS
CTIProgressBar
This element represents a progress bar or "throbber" that shows work is occurring. This element does not track actual progress time.
Properties
isRef=0; minOcc=0; maxOcc=1; content=complex Parents CTIElementSet,CTIParty Attributes Description Required? Type Attribute Name
Specifies the developer name for the progress bar Required
String ID
Specifies the text to use for the progress bar in the SoftPhone
Optional String
LABEL
CTIParty
This element represents a single participant in a call on a line. Properties
isRef=0; minOcc=0; maxOcc=unbounded; content=complex; mixed=false Parent
CTIElementSet Children
CTIInfoField,CTIProgressBar,CTIRelatedObjectSet Attributes
Description Required?
Type Attribute Name
Specifies the role of someone on a call from the perspective of the SoftPhone user:
<unspecified>
If the TYPE attribute is left unspecified, the SoftPhone user knows of only one other person Optional
String TYPE
on the call. The majority of calls fall into this category.
TRANSFERRED_FROM
The person who initiated a transfer. When this party type is specified, another party with a type of ORIGINAL_CALL_PARTICIPANT is also known to the SoftPhone user.
CONFERENCED_FROM
The person who initiated a conference call. When this party type is specified, another party with a type of ORIGINAL_CALL_PARTICIPANT is also known to the SoftPhone user.
Description Required?
Type Attribute Name
ORIGINAL_CALL_PARTICIPANT
The person who was on the original call but who did not initiate a conference or transfer. This party type is specified when transfers or conferences are initiated, or while a transferred call is in progress
CONFERENCED_PARTY
Any party who is actively participating in a conference call. This party type is specified for all participants of a conference as soon as a
conference call request has been accepted by a third party.
Transferred Call Scenario
For an example of how the Type attribute is used when a call is transferred, suppose there are three call center users: Marco, Rupert, and Caroline.
1. Marco calls Rupert. At this point, the TYPE attribute for both Marco and Rupert is left unspecified because Marco is only connected to Rupert and Rupert is only connected to Marco.
2. Marco initiates a transfer of the call to Caroline:
• From Marco's perspective, he has two separate calls occurring at the same time, both of which are with only one party. The TYPE attribute for Rupert's party and Caroline's party both remain unspecfied in Marco's SoftPhone.
• From Rupert's perspective, Marco has put him on hold and is still the only party on his call. The TYPE attribute for Marco's party remains unspecified in Rupert's SoftPhone.
• From Caroline's perspective, she is receiving a transfer request from Marco to handle a call with Rupert. The TYPE attribute for Marco's party is TRANSFERRED_FROM in her SoftPhone, while Rupert's party is
ORIGINAL_CALL_PARTICIPANT. 3. Caroline accepts the transferred call:
• From Marco's perspective he is no longer on any call.
• From Rupert's perspective, he is still on a call with one other person. The TYPE attribute for Caroline's party remains unspecified.
• From Caroline's perspective, Marco's and Rupert's party types remain TRANSFERRED_FROM and ORIGINAL_CALL_PARTICIPANT in her SoftPhone, even though Marco is no longer on the call.
Conference Call Scenario
For an example of how the Type attribute is used in a conference call, suppose there are three call center users: Marco, Rupert, and Caroline.
1. Marco calls Rupert. At this point, the TYPE attribute for both Marco and Rupert is left unspecified because Marco is only connected to Rupert and Rupert is only connected to Marco.
2. Marco initiates a conference call with Caroline:
• From Marco's perspective, he has two separate calls occurring at the same time, both of which are with only one party. The TYPE attribute for Rupert's party and Caroline's party both remain unspecfied in Marco's SoftPhone.
• From Rupert's perspective, Marco has put him on hold and is still the only party on his call. The TYPE attribute for Marco's party remains unspecified in Rupert's SoftPhone.
• From Caroline's perspective, she is receiving a conference request from Marco to join a call with Rupert. The TYPE attribute for Marco's party is CONFERENCED_FROM in her SoftPhone, while Rupert's party is
ORIGINAL_CALL_PARTICIPANT.
3. Caroline accepts the conferenced call. Marco, Rupert, and Caroline are now all on a call with two other parties, both of whom have type CONFERENCED_PARTY.
CTIInfoField
This element represents an information field that is not derived from a Salesforce record. Properties
isRef=0; minOcc=0; maxOcc=unbounded; content=complex; mixed=false Parent CTIParty Attributes Description Required? Type Attribute Name
Specifies the developer name for the information field Required
String ID
Specifies the text to use for the information field in the SoftPhone
Optional String
LABEL
Specifies the content of the information field Optional
String VALUE
Specifies the URL to link to from the information field value
Optional String
HREF
Specifies the target of the HTML anchor tag if an HREF attribute is included
Optional String
TARGET
CTIRelatedObjectSet
This element represents a set of links to Salesforce records that are related to an incoming call. You should define one
CTIRelatedObjectSet for each type of record that should be displayed. For example, if you wanted to display a set of cases
and a set of accounts, you should define two CTIRelatedObjectSets.
Properties
isRef=0; minOcc=0; maxOcc=unbounded; content=complex Parent CTIParty Children CTIRelatedObject Attributes Description Required? Type Attribute Name
Specifies the name for an object within Salesforce. You can find these names in the Apex Explorer. See the Required
String ID
Description Required?
Type Attribute Name
Apex API documentation for details (http://www.sforce.com/apidoc)
Specifies the text that is used for the related object set in the SoftPhone. This value is usually generated by Salesforce according to the object's ID.
Optional String
LABEL
CTIRelatedObject
This element represents a link to a single Salesforce record that is related to an incoming call. Properties
isRef=0; minOcc=0; maxOcc=unbounded; content=complex Parent CTIRelatedObjectSet Children CTIField Attributes Description Required? Type Attribute Name
Specifies the Salesforce ID for the record (for example, "003x0000004G")
Required String
ID
Specifies the text that is used for the record's link in the SoftPhone user interface
Optional String
LABEL
CTIField
This element represents a single field of a Salesforce record that is related to an incoming call. Properties
isRef=0; minOcc=0; maxOcc=unbounded; content=complex; mixed=false Parent CTIRelatedObject Attributes Description Required? Type Attribute Name
Specifies the developer name for the field (for example, Account_Name)
Required String
ID
Specifies the text that is used to display the field name in the SoftPhone (for example, "Account Name") Optional
String LABEL
Specifies the content of the field (for example, "salesforce.com, inc.")
Optional String
VALUE
CTILink
This element represents a single link to a URL. Properties
isRef=0; minOcc=0; maxOcc=unbounded; content=complex Parent CTIElementSet Attributes Description Required? Type Attribute Name
Specifies the text that should be used to display the link in the SoftPhone
Required String
TEXT
Specifies the URL destination of the link Required
String HREF
Specifies the window in which this link should open Optional
String TARGET
CTICallLog
This element represents a log for a single phone call. If this element occurs within a CTIPreviousCalls element, this is a previous call and will be displayed in a group with other previous calls. If this element does not occur within a CTIPreviousCalls element, this is the log for the call that is currently in progress and is displayed as such.
Properties
isRef=0; minOcc=0; maxOcc=unbounded; content=complex Parents
CTIUserInterface,CTIPreviousCalls Children
CTIWho,CTIWhat,CTIComments Attributes
Description Required?
Type Attribute Name
(Previous call logs only) Specifies the Salesforce ID of the call log task that is associated with this call. Current Optional
String ID
call logs do not require this value because call log tasks are not created until the call ends.
Specifies the subject field of the call log task that will be (or was) created for this call log
Required String
LABEL
(Current call logs only) If set to True, specifies that the call log should be displayed in the SoftPhone as Optional
Boolean OPEN
an expanded collapsible section. If set to False, this collapsible section is closed and the call log should not be displayed.
(Current call logs only) Specifies the line number to which this call pertains
Optional String
LINE
CTIComments
This element represents the text box (for a current call log), or the static text (for a previous call log), that displays any call comments that the user wants to associate with this call log.
Properties
isRef=0; minOcc=0; maxOcc=1; content=complex Parents CTILineOnlyElementSet,CTICallLog Attributes Description Required? Type Attribute Name
Specifies the text that should appear in the comments area
Optional String
VALUE
CTIWho
This element represents an available option for the "Who" portion of a call log. A "Who" can be a contact, lead, or person account.
Properties
isRef=0; minOcc=0; maxOcc=unbounded; content=complex Parent CTICallLog Attributes Description Required? Type Attribute Name
Specifies the Salesforce ID of the contact, lead, or person account
Required String
ID
Specifies the formatted text that should be used to display the contact, lead, or person account in the SoftPhone (for example, "Contact: Henry James") Optional
String LABEL
If set to True, specifies that this contact, lead, or person account is currently selected in the SoftPhone Optional
Boolean SELECTED
CTIWhat
This element represents an available option for the "What" portion of a call log. A "What" can be any object other than a contact, lead, or person account.
Properties
isRef=0; minOcc=0; maxOcc=unbounded; content=complex Parent
CTICallLog
Attributes
Description Required?
Type Attribute Name
Specifies the Salesforce ID of the object Required
String ID
Specifies the formatted text that should be used to display the object (for example, "Case: 00001002") Optional
String LABEL
If set to True, specifies that this contact, lead, or person account is currently selected in the SoftPhone Optional
Boolean SELECTED
CTIInteractiveControlContainer
This group is comprised of the set of elements that show controls with which an agent can interact.