SDK Concepts

This chapter covers the following topics:

• Architecture
• Adapter Implementation
• Oracle Telephony Adapter API Objects
• TeleDeviceFactory
• TelesetDevice
• RoutePointDevice
• Call Data
• Media Item ID
• Media Item ID Model

Architecture

The Oracle Telephony Adapter Server consists of a communications core (Oracle Telephony Adapter Server Runtime), the Oracle Telephony Adapter APIs, and the adapter code that implements and writes to the Oracle Telephony Adapter APIs.

The following figure illustrates Oracle Telephony Adapter Server Architecture.

As the previous figure illustrates, the Oracle Telephony Adapter Server consists of Oracle Telephony Adapter Server Runtime, Oracle Telephony Adapter Server APIs, and the adapter implementation (plug-in). The Oracle Telephony Adapter Server connects the telephony switch and CTI middleware with Oracle Interaction Center.

Adapter Implementation

The adapter implementation is platform-specific custom code that maps telephony platform (ACD/PBX and CTI middleware) APIs to Oracle Telephony Adapter APIs.

Oracle Telephony Adapter API Objects

Oracle Telephony Adapter APIs specify three objects that the adapter code must implement and through which it must communicate. The objects are TeleDeviceFactory, TelesetDevice, and RoutePointDevice.

TeleDeviceFactory

Oracle uses the TeleDeviceFactory object to allocate and deallocate switch resources. Only the Teleset and Route Point resources can be allocated.

TelesetDevice

A teleset device represents a physical telephone (currently only digital telesets, not analog telesets) that is used by an agent. Agents log into their telesets and use this object to perform various call control functions, such as placing a call, putting a call on hold and hanging up a call. The teleset device also relays switch events signifying state changes and call progression from the telephony platform to Oracle Interaction Center.

For Advanced Integration, the teleset device has the following characteristics:

• Each teleset is displayed as three lines on the Oracle softphone.

• Each line can hold one call.

• Depending on the telephony platform, one key on the physical teleset maps to one or more lines on the Oracle softphone. For example, for Avaya Definity one physical teleset is programmed with three keys that share the same "station number." In this case,on the Oracle softphone one line represents one key of the Avaya physical teleset. For Nortel Meridian, one physical teleset is programmed with two keys, Personal DN and ACD DN. In this case, on the softphone, line one represents the Personal DN key, line two represents the ACD DN key, and line three represents a consultation call placed from either key.

• Most events that are fired to the Oracle Interaction Center must specify the line on which the event occurs (line indexes 0, 1 or 2).

• Most call control commands are performed on the line that is specified by the API call, such as holdCall. The API calls makeCall and consultationCall can return events on a different line.

• Only one consultation call can be placed at a time. Therefore, only one transfer or conference can be pending.

RoutePointDevice

A route point device represents a switch queue that can be either a controlled queue, in which Oracle Advanced Inbound Telephony actively routes calls, or a monitored queue in which Oracle Advanced Inbound Telephony only keeps track of the queued calls while the switch does the actual call routing.

The route point device has the following characteristics:

• Each route point has a queue of pending calls.

• Each call in the queue is identified by a call identifier, usually the call ID that is assigned by the telephony platform.

• The call identifier is used by call control commands. Any events that are fired must contain the call identifier.

• If the call ID changes due to a blind transfer, then the corresponding call identifier should not change.

Call Data

Call data is any data that is associated with a call, specifically the ANI, DNIS and any IVR data. This data is used by Oracle Interaction Center to properly classify and route the call and is also the basis for a screen pop. The adapter expects call data from the telephony platform at the start of a call or soon after the start.

Media Item ID

Oracle Interaction Center keeps track of logical interactions that are identified by a Media Item Identifier (Media Item ID). Although a switch-specific call ID may change as the call is transferred, the Media Item ID must remain the same. When the Media Item ID is assigned by Oracle, it is the responsibility of the implementer to ensure that it is propagated as the call moves from agent to agent. If the call ID on a line changes due to a transfer or conference completion, then the corresponding Media Item ID does not change.

Media Item IDs are assigned by Oracle and passed to the Adapter by way of the TelesetDevice and RoutePointDevice methods. Maintaining the correct Media Item ID in call events is essential to ensure that transfer and conference scenarios are processed correctly.

Media Item ID Model

The Media Item ID model has the following characteristics.

Note: The following examples do not show all events.

Oracle Interaction Center Actions

Oracle Interaction Center Actions	Adapter Server Actions/States	Oracle Interaction Center States
A: makeCall (MI: 1, Dest: B)4	A: dial (Dest: B) map resultant call id 1 to MI 11
	A: beginCallEvent (MI: 1, line: 0)2	A: line 0 has MI 11
	B: beginCallEvent (MI: 1, line: 0)2	B: line 0 has MI 11
A: releaseCall (line: 0)	A: hangup (call id 1)
	A: callReleasedEvent (line: 0)	A: line 0 is clear
	B: callReleasedEvent (line: 0)	B: line 0 is clear

Customer Actions

Customer Actions	Adapter Server Actions/States	Oracle Interaction Center States
X: calls A	A: beginCallEvent (MI: n/a, line:0) Oracle Telephony Adapter Server does not know MI1	A: line 0 has MI 24: OIC assigns Media Item ID to call
X: hangup call	A: callReleasedEvent (line:0)	A: line 0 is clear

Customer/ Oracle Interaction Center Actions

Customer/OIC Actions	Adapter Server Actions/States	Oracle Interaction Center States
X: calls A	A: beginCallEvent (MI: n/a, line:0) // call id 2, Oracle Telephony Adapter Server does not know MI1	A: line 0 has MI 33: OIC assigns Media Item ID to call
A: consult (MI1: 3, line: 0, Dest: B)4	A: consult (call id: 2, Dest: B) // map call id 2 to MI1 3 // map consult call id 3 to MI 3
	A: beginCallEvent (MI: 3, line: 1)2	A: line 1 has MI 3
	B: beginCallEvent (MI: 3, line: 0)2	B: line 0 has MI 3
A: transfer (line: 1, old line: 0)	A: transfer (call ID 3, call ID 2)
	A: callReleasedEvent (line: 0)	A: line 0 is clear
	A: callReleasedEvent (line: 1)	A: line 1 is clear
	B call ID changes (ABA model)5	No event to OIC

Footnotes

1. Media Item ID

2. If an incoming call already has a Media Item ID, then it must be passed to the receiving device.

3. If an incoming call does not have a Media Item ID, then Oracle Interaction Center assigns a new Media Item ID and uses it with any future consultation calls.

4. New calls are assigned a new Media Item ID when the dial command is made.

5. There is a one-to-many relationship between Media Item ID and switch-specific call IDs. If the call ID changes while the actual call is transferred or conferenced, then the Media Item ID should remain the same.