This chapter covers the following topics:
This chapter describes Oracle Telephony Adapter SDK Basic Integration, and explains how to use the infrastructure and facilities of Basic Integration to integrate the Oracle E-Business Suite with a third-party telephony system.
This information is intended for developers and consultants who intend to use Oracle Telephony Adapter SDK Basic Integration to integrate Oracle E-Business Suite with a third-party telephony vendor.
Basic Integration of Oracle Telephony Adapter SDK consists of the following:
Oracle Universal Work Queue Client
Basic Telephony SDK plug-in
As the following diagram shows, Basic Integration integrates the telephony system (middleware, PBX), or third-party desktop software, with the Oracle Universal Work Queue client in the Oracle E-Business Suite.
Basic Integration Architecture
The Basic Telephony SDK plug-in enables third-party telephony systems to communicate with the Oracle E-Business Suite by using one of two types of HTTP messages:
Callout: Messages are sent from Oracle E-Business Suite to the third-party system using a HTTP GET request.
Event: Messages are sent from a third-party system using an HTTP POST request.
The following diagram illustrates sending callouts from the HTTP client to the third-party telephony system, and events from the third-party telephony system to the HTTP listener.
Callouts and Events
The components of Basic Integration are explained in the following sections.
The Basic Integration user interface includes the following components.
On the Oracle Universal Work Queue form, "Basic Telephony" appears on the left Queue Selector Pane whenever Basic Telephony is enabled. Selecting Basic Telephony on the Queue Selector Pane displays the right Queue Details Pane. A row with the title "<ANY>" appears. When in the Basic Telephony mode, the Get Work button does not appear. Double clicking in the <ANY> row triggers Get Work.
icWork Controller is a floating window that is used to Stop Media and to get Next Media.
The following paragraphs explain the Basic Integration actions and their corresponding user actions.
When a user opens the Oracle Universal Work Queue form, the basic framework elements set up and prepare Oracle Universal Work Queue for use. The Basic SDK client plug-in is loaded and performs the following actions:
Loads the user profile values from the database and determines how to connect to the third-party system.
Starts the HTTP listener on a randomly-allocated port or the optionally-specified port.
Sends Register and Login callouts to the third-party system to establish a session.
Starts the reconnect checking process.
The right Queue Details Pane displays <ANY>, and the Basic SDK client plug-in takes no action.
Basic SDK client plug-in sends Ready callout to the third-party system and sets itself in Get Work mode if there is no prior ScreenPop event received. Otherwise, the ScreenPop event is delivered.
Basic SDK client plug-in sends Ready callout to the third-party system and sets itself in Get Work mode if there is no prior ScreenPop event received. Otherwise, the ScreenPop event is delivered.
Basic SDK client plug-in sends NotReady callout to the third-party system and sets itself in non-Get Work mode.
The Basic SDK client plug-in sends Logout and Unregister to the third-party system.
Basic SDK client plug-in stops HTTP listener and frees any resources.
Basic SDK integration sends a ScreenPop event to the Basic SDK client plug-in.
Basic SDK client plug-in delivers the data to Oracle Universal Work Queue for screen pop if it is in Get Work mode. Otherwise, it puts the event in its FIFO queue.
Basic SDK client plug-in creates a media item record in Oracle Customer Interaction History.
Basic SDK integration sends a CallEstablished event to the Basic SDK client plug-in.
Basic SDK client plug-in creates a media item life cycle segment in Oracle Customer Interaction History.
Basic SDK integration sends a CallReleased event to the Basic SDK client plug-in.
Basic SDK client plug-in updates the media item life cycle segment in Oracle Customer Interaction History.
The dial string entered in the text field on Basic Panel is sent with MakeCall callout to a third-party system.
The following software requirements and development strategies apply to the Oracle Telephony Adapter SDK Basic Integration.
The minimal patch level required by Basic Telephony SDK is Release 11.5.8 + Interaction Center Family Pack P.
Because the Basic Telephony SDK is defined in HTTP and XML, developers can use any programming language in which HTTP request processing can be implemented easily.
The following two examples demonstrate different ways of developing Basic Telephony Integration.
Client-based (recommended): In the client-based strategy, integration is done on client-side third-party software, such as a softphone, and is installed on each desktop machine. The Basic SDK communicates locally with the third-party software.
Server based: In the server-based strategy, custom integration is done on a server-based platform and is installed centrally on the server. No client software is installed on the desktop machine. Basic SDK communicates with third-party software through the LAN.
This section describes the implementation of Basic Integration.
Callouts are messages sent from Oracle E-Business Suite to the third-party system using HTTP GET requests. Developers must implement an HTTP listener that is capable of handling the HTTP GET requests specified in this document. The URL to the HTTP listener is then provided to the Basic SDK client plug-in through the use of a profile option. Parameters are passed to the URL using GET request semantics (CGI parameters). All callouts are handled by one single URL with the FunctionName parameter being a different value.
Definition: Establish a session with the telesetNumber specified and notify third-party system on the IP address and port to which the Basic SDK client plug-in is listening.
Parameter Name | Value |
---|---|
FunctionName | Register |
telesetNumber | telesetNumber entered by agent |
agentID | ACD agent ID |
ipAddress | ipAddress of the Basic SDK client plug-in HTTP Listener |
port | Port of the Basic SDK client plug-in HTTP Listener |
URL example:
http://host:port/?FunctionName=Register&telesetNumber=1001&agentID=10001&ipAddress=130.46.1.1&port=8088
Definition: End the session with the telesetNumber specified.
Parameter Name | Value |
---|---|
FunctionName | Unregister |
telesetNumber | the telesetNumber entered by agent |
agentID | ACD agent ID |
URL example:
http://host:port/?FunctionName=Unregister&telesetNumber=1001&agentID=10001
Definition: (Optional) Log in the agent to the specified Teleset Number. The third-party system or developer can decide whether to react to this callout, if manual login is desired.
Parameter Name | Value |
---|---|
FunctionName | Login |
telesetNumber | the telesetNumber entered by agent |
agentID | ACD agent ID |
agentPassword | ACD password of the agent |
agentQueue | ACD queue the agent should login to |
URL example:
http://host:port/?FunctionName=Login&telesetNumber=1001&agentID=10001&agentPassword=123&agentQueue=1234
Definition: (Optional) Log out the agent to the specified Teleset Number. The third-party system or developer can decide whether to react to this callout.
Parameter Name | Value |
---|---|
FunctionName | Logout |
telesetNumber | the telesetNumber entered by agent |
agentID | ACD agent ID |
agentPassword | ACD password of the agent |
agentQueue | ACD queue the agent should login to |
URL example:
http://host:port/?FunctionName=Logout&telesetNumber=1001&agentID=10001&agentPassword=123&agentQueue=1234
Definition: Agent is ready for work.
Parameter Name | Value |
---|---|
FunctionName | Ready |
telesetNumber | TelesetNumber entered by agent |
agentID | ACD agent ID |
URL example:
http://host:port/?FunctionName=Ready&telesetNumber=1001&agentID=10001
Definition: Agent is not ready for work.
Parameter Name | Value |
---|---|
FunctionName | NotReady |
telesetNumber | TelesetNumber entered by an agent |
agentID ACD | ACD agent ID |
URL example:
http://host:port/?FunctionName=NotReady&telesetNumber=1001&agentID=10001
Definition: Make a call.
Parameter Name | Value |
---|---|
FunctionName | MakeCall |
telesetNumber | TelesetNumber entered by agent |
agentID ACD | ACD agent ID |
dialString | Destination number to dial |
URL example:
http://host:port/?FunctionName=MakeCall&telesetNumber=1001&agentID=10001&dialString=6509991111
Definition: Check if the third-party system is up and running. This callout is called periodically by the Basic SDK client plug-in to detect lost connection and reconnect. You can configure the interval between each callout.
Parameter Name | Value |
---|---|
FunctionName | CheckStatus |
URL example:
http://host:port/?FunctionName=CheckStatus
For each callout the developer must return a 200 HTTP response code indicating that the callout has processed the request. Successful callouts return an HTTP response with the 200 response code and no content. Errors in the HTTP response message may be reported using the following XML format:
<CCTSDK>
<event name="Error">
<data name="occtErrorMsg" value="error message here"/>
</event>
</CCTSDK>
As part of a screen pop, you can open a form in Create or Edit mode, as in creating a service request and viewing or editing a service request. This topic describes how to define the mode in which the form opens.
Click the responsibility Universal Work Queue - Work Provider Administration > Work Actions.
Click Create Work Action.
Create a work action of type Media.
The work action is now listed in the Media action column of the UWQ media action tab. The PL/SQL procedure in the Work Action - Action Details page determines which form and in what mode it opens. For an example, refer to the work action Service Requests Media Function, which has the PL/SQL procedure SR_UWQ_INTEG.SR_UWQ_FOO_FUNC (cssruwqb.pls).
Events are messages sent from the third-party system to the Basic SDK client plug-in using HTTP POST request. You can construct the URL of the Basic SDK client plug-in by using the IP address and port parameters from Register Callout. The request body must be an XML formatted message that is defined as follows:
Note: Formatting is based on standard XML conventions, for example white spaces are ignored. The value is case sensitive.
<CCTSDK>
<event name="eventName">
<data name="name1" value="value1"/>
<data name="name2" value="value2"/>
<data name="name3" value="value3"/>
...
</event>
</CCTSDK>
Definition: ScreenPop event triggers a screen pop in the Oracle E-Business Suite. Developers must determine when to send a ScreenPop event, typically when the agent gets an inbound call. Developers must decide whether to send a ScreenPop event for every call or only for certain types of calls. For example, internal or outbound calls are not often considered for screen pops.
XML example:
<CCTSDK>
<event name="ScreenPop">
<data name="occtSourceID" value="1"/>
<data name="occtANI" value="50666546"/>
<data name="occtDNIS" value="7404"/>
</event>
</CCTSDK>
Definition: Indicates that a call is established. CallEstablished event triggers the creation of a life cycle segment in Oracle Customer Interaction History. The start timestamp of the segment will be logged. This event must be sent after ScreenPop event.
Parameter Name | Value |
---|---|
occtSourceID | Logical ID used to connect between multiple events of the same physical call. Multiple events generated from the same physical call must have the same occtSourceID value, that is, telephony middleware call IDs. This value must be a number. Valid values are 0, and positive and negative numbers with magnitude 1.0E-130 to 9.99..E125 |
XML example:
<CCTSDK>
<event name="CallEstablished">
<data name="occtSourceID" value="1"/>
</event>
</CCTSDK>
Definition: Indicates a call is released. CallReleased event triggers the life cycle segment that is being updated in Oracle Customer Interaction History. The end timestamp and the duration of the segment are logged. This event must be sent after CallEstablished.
Parameter Name | Value |
---|---|
occtSourceID | Logical ID used to connect between multiple events of the same physical call. Multiple events generated from the same physical call must have the same occtSourceID value, that is, telephony middleware call IDs. This value must be a number. Valid values are 0, and positive and negative numbers with magnitude 1.0E-130 to 9.99..E125 |
XML example:
<CCTSDK>
<event name="CallReleased">
<data name="occtSourceID" value="1"/>
</event>
</CCTSDK>
In addition to the keys specified in the ScreenPop event section, the following table lists keys that may also be sent by the third-party system as name/value pairs as part of the ScreenPop event. These keys may be used for out-of-the-box screen pops by Oracle Customer Care and Oracle TeleSales.
Interaction Key | Description |
---|---|
ContactNum | Oracle TeleSales Key 3 |
PromotionCode | Oracle TeleSales Key 4 |
AccountCode | Oracle TeleSales Key 5 |
QuoteNum | Oracle TeleSales Key 6 |
CustomerID | Oracle TeleSales Key 7 |
Product | Oracle TeleSales Key 8 |
SystemName | Oracle TeleSales Key 9 |
ContractNum | Oracle TeleSales Key 10 |
PreferredID | Oracle TeleSales Key 11 |
ScreenPopType | Oracle TeleSales Key 12 |
occtCallBirthTime | Oracle TeleSales Key 13 |
occtCallAnswerTime | Oracle TeleSales Key 14 |
CustomerProductID | Oracle TeleSales Key 15 |
InventoryItemID | Oracle TeleSales Key 16 |
InvoiceNum | Oracle TeleSales Key 17 |
LotNum | Oracle TeleSales Key 18 |
OrderNum | Oracle TeleSales Key 19 |
ProductName | Oracle TeleSales Key 20 |
PurchaseOrderNum | Oracle TeleSales Key 21 |
ReferenceNum | Oracle TeleSales Key 22 |
RevisionNum | Oracle TeleSales Key 23 |
RMANum | Oracle TeleSales Key 24 |
SerialNum | Oracle TeleSales Key 25 |
ServiceRequestNum | Oracle TeleSales Key 26 |
CustomerNum | Oracle TeleSales Key 27 |
CustomerName | Oracle TeleSales Key 28 |
occtANI | Oracle TeleSales Key 29 |
occtClassification | Oracle TeleSales Key 31 |
LanguageCompetency | Language Competency |
KnowledgeCompetency | Knowledge Competency |
ProductCompetency | Product Competency |
occtMediaType | Media Type |
employeeID | Employee ID |
occtMediaItemID | Media Item ID |
AccountNum | Account Number |
SiteNum | Site Number |
RepairNum | Repair Number |
DefectNum | Defect Number |
CustomerStatus | Customer Status |
EventCode | Event Registration Code |
CollateralReq | Collateral Request Number |
SocialSecurityNumber | Social Security Number |
CAMPAIGN_SCHEDULE_NAME | Campaign Schedule Name |
CompetencyType | Competency Type |
Competency | Competency |
occtCreationTime | Time of the Day |
MarketingPIN | Marketing PIN |
ServiceKey | Service Key |
ContractNumModifier | Contract Number Modifier |
Example of XML for ScreenPop Event with CustomerID:
<CCTSDK>
<event name="ScreenPop">
<data name="occtSourceID" value="134"/>
<data name="CustomerID" value="1234567"/>
<data name="occtANI" value="40666546"/>
<data name="occtDNIS" value="7404"/>
</event>
</CCTSDK>
Related Topics
Oracle Advanced Inbound Telephony Implementation Guide
Oracle Customer Care User Guide
Oracle TeleSales User Guide
This section includes the following topics.
Media Action must be defined in the Oracle Universal Work Queue Media Action HTML administration page for the proper Oracle E-Business Suite application to pop on the ScreenPop event. The following is an example to pop Customer Care Form on any classification and Oracle Universal Work Queue Diagnostics Form on Diagnostics classification.
Media Type | Classification | Media Action |
---|---|---|
Basic Telephony | Customer Care Media Function | |
Basic Telephony | Diagnostics | Universal Work Queue Media Diagnostics Function |
Basic Web Callback | Web callback integration with Oracle iStore and Oracle iSupport |
Note: Basic Telephony is typically implemented with inbound telephony and Web callback as the only media. In these cases, Basic Telephony and Basic Web Callback are enabled and all other media queues are disabled.
If your system supports Basic Integration, the only supported media types are Basic Telephony and Basic Web Callback. Therefore, enable only those profile options for media. Set user profile options (site-level or user-level) as shown in the following table.
Profile | Value |
IEU: Queue: Basic Telephony | Yes |
IEU: Queue: Inbound Telephony | No |
IEU: Queue: Advanced Outbound | No |
IEU: Queue: Inbound E-mail | No |
IEU: Queue: Acquired E-mail | No |
IEU: Queue: Web Collaboration | No |
IEU: Queue: Web Callback | Yes |
Set additional profile options at the user-level as shown in the following table.
Profile | Meaning | Example |
CCT: Basic Telephony: ACD ID | <agent acd id> | |
CCT: Basic Telephony: ACD Password | <agent acd password> | |
CCT: Basic Telephony: ACD Queue | <agent acd queue> | |
CCT: Basic Telephony: Listener Port | (Optional) Listener port for the Basic SDK HTTP Listener. The port where the Universal Work Queue client listens for incoming events. Each instance of a basic teleset or Universal Work Queue plug-in must have a unique listener port. If you do not specify a value, then the UWQ client allocates the port randomly, determined by the Java Socket API which guarantees availability, that is, the port already in use will not be allocated again. It does not use a specific range. Formatting is based on standard XML syntax:
|
1234 |
CCT: Basic Telephony: Reconnect Interval | (Optional) Number of seconds of the reconnect interval when the Universal Work Queue plug-in tries to ping the basic SDK implementation. If the Basic SDK implementation does not respond to the ping request, then an error event is thrown. | 10 |
CCT: Basic Telephony: Third Party URL | (Required) Third-party URL implementing callout handling. The HTTP listener where the Basic SDK implementation waits for callouts from the Universal Work Queue client. | http://localhost:9099 |
CCT: Basic Telephony: Log Level | (Optional) Error, warning, info or verbose | error |
CCT: Basic Telephony: IC Plugin: Enable Log Window | (Optional) Yes/no, enable Log tab on Basic Panel | yes |
CCT: Basic Telephony: IC Plugin: Enable Event Window | (Optional) Yes/no, enable Event tab on Basic Panel | yes |
CCT: Basic Telephony: IC Plugin: Enable ScreenPop Window | (Optional) Yes/no, enable ScreenPop tab on Basic Panel | yes |
To enable Basic Web Callback, extend Basic Integration by implementing the dialCanonical method. In the DialCanonical method, third party integrators must use an agent's telephone to dial a customer's telephone number that is in the canonical format. One of the parameters sent in DialCanonical is application data (appData), which must be sent back to the client SDK plugin in the Call Established event for the physical call made in DialCanonical. The appData must be returned as the key value pair {occtAppData,appData}.
Example callout URL:
http://<dest-server-url>?FunctionName=DialCanonical&telesetNumber=70011&agentID=7011&dialString=1234567&appData=10325
The following parameters apply to Basic Web Callback.
FunctionName = DialCanonical
telesetNumber = TelesetNumber entered by the agent.
agentID = ACD agent ID
dialString = Dial string in the canonical form
appData = Application data attached to the callout.
Web Callback requests are made by way of Oracle iStore and Oracle iSupport. Administrators of these applications need to enable Web callback by selecting the default seeded server group BASIC_SDK in Oracle iStore and Oracle iSupport.
The following modes are supported with Basic Web Callback:
This is the default mode. In this mode, when agents have selected GetWork for Basic Web Callback, the system successively assigns Web callback requests to the agent. If no Web callback request is currently available, then the system polls until a Web callback request becomes available. The polling interval can be set as the profile value CCT: Basic WebCallback: Polling Interval in seconds. The default polling interval is 30 seconds.
When a Web callback request is assigned to an agent, a screen pop occurs at the agent's desktop and the callback phone call is immediately dialed out automatically.
In this mode, when a Web callback request is assigned to an agent, a screen pop occurs, but the callback phone call is not dialed out. Instead, the callback phone number is displayed and the agent is required to click Dial on the phone for the dial out to occur. Agents should use this mode when they need time to read the customer information in the screenpop before dialing out.
To set up preview dialing, set the profile option CCT: Basic WebCallback: Enable Preview to Yes.
In this mode, when a Web callback request is assigned to an agent, a screen pop occurs, but the callback phone call is not made for a specified time, that is, the preview time interval. When the preview time interval expires, the callback phone call automatically dials out. Use this mode when you need to set a cap on the amount of time an agent can use to preview customer information.
To set up Timed Preview Dialing, first enable Preview Dialing, and then specify the preview time interval in the profile option CCT: Basic WebCallback: Maximum Preview Interval.
Basic Implementation can be tested in one of two ways:
Testing with SDK Integrated Test Utility
Testing with an Oracle E-Business Suite application
The Basic SDK Implementation can be tested using the SDK Integrated Test Utility. This is useful in the development stage of the Basic SDK Implementation when access to Oracle E-Business Suite is not available. The SDK Integrated Test Utility emulates the Basic SDK client plug-in and enables developers to invoke callouts to their Basic SDK implementations and receive HTTP/XML events.
Start the SDK Integrated Test Utility
Run sdkrun.bat.
In the TeleDevice Test Utility tab, select the Basic Teleset tab.
Select a row and right click.
A menu appears.
Select Assign.
A dialog box appears.
Enter the URL, agent ID, teleset ID and listener port.
Click OK.
The selected row is filled with agentID and telesetID information.
Right click the selected row.
Choose Connect.
An internal window (the Basic Teleset Watch window) appears.
The Basic Teleset Watch Window consists of the following components:
Pull Down menu Event and Method
Current Event Display
Developers can use the pull down menu Method to invoke HTTP callouts to their own implementation. HTTP/XML events received by the Basic Teleset Watch Window can be viewed in the Current Event Display area. Developers can also use the Event pull down menu to display the list of events received by the Basic Teleset.
Use the configuration described in Deploying Basic Integration to create a user with the appropriate Oracle E-Business Suite responsibility. After you launch the Universal Work Queue form, perform the inbound call test listed in the following table.
The Basic Integration sample code consists of four Java source files in the directory oracle/apps/cct/java/sample/basic.
BasicSDKException.java
BasicSDKManager.java
BasicSDKBootstrap.java
SampleBasicSDKManager.java
In the following example implementation of the Basic SDK integration with Switch Simulator, the following functions are implemented.
The following table describes the location of the Basic Integration sample code and the functionality supported by the corresponding sample implementation.
Location | Sample Code | Supported Functions |
---|---|---|
oracle/apps/cct/java/sample/basic | BasicSDKBootsrap.java, BasicSDKException.java, BasicSDKManager.java, SampleBasicSDKManager.java | Basic SDK Integration supports all functions. |
Switch Simulator is one of the Oracle Interaction Center server processes that is used in demonstration environments where a real switch is not available. The simulator supports teleset and route point functions. Access Switch Simulator programmatically by using the OpenTel Bean API (a Java API, package oracle.apps.cct.openTel.bean). The simulator models each line of the teleset and route point as extension objects, which you can access by using the OpenTelExtensionBean. Switch Simulator sends OpenTel events.
In the following example implementation, Basic SDK Integration acts as a bridge between the Basic SDK client plug-in residing in Oracle E-Business Suite and the Switch Simulator. SampleBasicSDKManager handles HTTP callouts, which are translated to OpenTel Bean API. OpenTel events sent by the Switch Simulator are received and translated into XML, and then sent to the Basic SDK client plug-in using HTTP.
Basic Integration Example Scenario
The following descriptions explain how each function is implemented.
When SampleBasicSDKManager receives a Register request, it creates an OpenTelExtensionBean object that connects to the specified extension running in Switch Simulator. An event listener is added to the OpenTelExtensionBean object so that OpenTel events can be received.
When SampleBasicSDKManager receives an Unregister request, it disposes of the OpenTelExtensionBean object and removes any event listener from it.
When SampleBasicSDKManager receives a MakeCall request, it looks up the specified OpenTelExtensionBean object and invokes the makeCall API.
ScreenPop event is sent when an OpenTel event of INBOUND_CALL and state RECEIVE is received.
CallEstablised event is sent when an OpenTel event of TP_ANSWERED and state CONNECT is received. The primary call ID of the current call is retained.
CallReleased event is sent when an OpenTel event of state NULL is received and there is a current call.