Basic Integration

This chapter covers the following topics:

Introduction

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.

Architecture

Basic Integration of Oracle Telephony Adapter SDK consists of the following:

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 picture is described in the document text

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:

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 picture is described in the document text

Understanding Basic Integration

The components of Basic Integration are explained in the following sections.

User Interface

The Basic Integration user interface includes the following components.

Oracle Universal Work Queue

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

icWork Controller is a floating window that is used to Stop Media and to get Next Media.

User Actions and Corresponding Basic Telephony Integration Actions

The following paragraphs explain the Basic Integration actions and their corresponding user actions.

User Opens the Oracle Universal Work Queue Form

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:

User Selects the Basic Telephony Work Queue

The right Queue Details Pane displays <ANY>, and the Basic SDK client plug-in takes no action.

User Selects the Basic Telephony <ANY> Record

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.

User Selects End Interaction on E-Business Suite Form

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.

User Selects Stop Media Button on icWork Controller

Basic SDK client plug-in sends NotReady callout to the third-party system and sets itself in non-Get Work mode.

User Closes Oracle Universal Work Queue Form

User Receives an Inbound Call

User Answers an Inbound Call

User Releases an Inbound Call

User Selects Dial on the Basic Panel

The dial string entered in the text field on Basic Panel is sent with MakeCall callout to a third-party system.

Software Requirements and Development Strategies

The following software requirements and development strategies apply to the Oracle Telephony Adapter SDK Basic Integration.

Minimum Patch Level

The minimal patch level required by Basic Telephony SDK is Release 11.5.8 + Interaction Center Family Pack P.

Programming Languages

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.

Development Strategies

The following two examples demonstrate different ways of developing Basic Telephony Integration.

Implementing Basic Integration

This section describes the implementation of Basic Integration.

Implementing Callouts

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.

Register

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

Unregister

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

Login

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

Logout

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

Ready

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

NotReady

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

MakeCall

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

CheckStatus

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

Error Reporting

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>

Setting the Mode of a Screen-Pop Form

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.

  1. Click the responsibility Universal Work Queue - Work Provider Administration > Work Actions.

  2. Click Create Work Action.

  3. 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).

Implementing Events

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>

ScreenPop

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.

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. SourceID values must be a number. Valid values are 0 and positive and negative numbers with magnitude 1.0E-130 to 9.99..E125
occtANI ANI. Must be <= 30 characters.
occtDNIS DNIS. Must be <= 30 characters.
occtClassification (Optional) Field passed to Oracle Universal Work Queue for determining the appropriate media action for this ScreenPop event. Must be <= 64 characters.

XML example:

<CCTSDK>


<event name="ScreenPop">


<data name="occtSourceID" value="1"/>


<data name="occtANI" value="50666546"/>


<data name="occtDNIS" value="7404"/>


</event> 


</CCTSDK>

CallEstablished (Optional)

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>

CallReleased (Optional)

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>

Additional Interaction Keys

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

Deploying Basic Integration

This section includes the following topics.

Media Action Configuration

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

User Profile Configuration

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:

  • White spaces are ignored.

  • Values are case sensitive.

  • Character set is US-ASCII.

 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

Implementing Basic Web Callback

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

Parameters

The following parameters apply to Basic Web Callback.

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.

Basic Web Callback Modes

The following modes are supported with Basic Web Callback:

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.

Basic Web Callback with Preview Dialing

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.

Basic Web Callback with Timed Preview Dialing

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.

Testing Basic Implementation

Basic Implementation can be tested in one of two ways:

Testing with SDK Integrated Test Utility

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.

  1. Start the SDK Integrated Test Utility

  2. Run sdkrun.bat.

  3. In the TeleDevice Test Utility tab, select the Basic Teleset tab.

  4. Select a row and right click.

    A menu appears.

  5. Select Assign.

    A dialog box appears.

  6. Enter the URL, agent ID, teleset ID and listener port.

  7. Click OK.

  8. The selected row is filled with agentID and telesetID information.

  9. Right click the selected row.

  10. Choose Connect.

    An internal window (the Basic Teleset Watch window) appears.

The Basic Teleset Watch Window consists of the following components:

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.

Testing with Oracle an Oracle E-Business Suite Application

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.

# Procedure Expected Outcome Result Comments
A1 Launch Universal Work Queue form Extension Number Dialog Appears    
A2 Enter Extension Number Universal Work Queue Client should be launched without error message. Basic SDK Integration should receive Register and Login callouts.    
A3 Double click Basic Telephony <ANY> record Basic SDK Integration should receive Ready callout    
A4 Generate an inbound call to the agent logged on Basic SDK Integration should send ScreenPop event. A screen pop should occur.    
A5 Agent answer the call Basic SDK Integration should send CallEstablished event.    
A6 Agent release the call Basic SDK Integration should send CallReleased event    
A7 Press End Interaction Basic SDK Integration should receive Ready callout    
A8 Press Stop Media button on icWork Controller Basic SDK Integration should receive NotReady callout    
A9 Close from Universal Work Queue Oracle Universal Work Queue form should be successfully closed, Basic SDK Integration should receive Logout and Unregister callouts    

Sample Code

The Basic Integration sample code consists of four Java source files in the directory oracle/apps/cct/java/sample/basic.

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

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.

Design

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 picture is described in the document text

The following descriptions explain how each function is implemented.

Register Callout

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.

Unregister Callout

When SampleBasicSDKManager receives an Unregister request, it disposes of the OpenTelExtensionBean object and removes any event listener from it.

MakeCall Callout

When SampleBasicSDKManager receives a MakeCall request, it looks up the specified OpenTelExtensionBean object and invokes the makeCall API.

ScreenPop Event

ScreenPop event is sent when an OpenTel event of INBOUND_CALL and state RECEIVE is received.

CallEstablished Event

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

CallReleased event is sent when an OpenTel event of state NULL is received and there is a current call.