Oracle Real-Time Collaboration

(1)

Oracle® Real-Time Collaboration

Integration Services Guide

Release 2.0.4.3

Part No. B12158-02

May 2004

Use this guide to integrate your application with Oracle Real-Time Collaboration.

(2)

Oracle Real-Time Collaboration Integration Services Guide, Release 2.0.4.3 Part No. B12158-02

Contributing Author: Vimal Chopra, Barbara Heninger, Vasudeva Nori, Cynthia Stevens Contributor: Susan Rendina

The Programs (which include both the software and documentation) contain proprietary information; they are provided under a license agreement containing restrictions on use and disclosure and are also protected by copyright, patent, and other intellectual and industrial property laws. Reverse engineering, disassembly, or decompilation of the Programs, except to the extent required to obtain interoperability with other independently created software or as specified by law, is prohibited.

The information contained in this document is subject to change without notice. If you find any problems in the documentation, please report them to us in writing. This document is not warranted to be error-free. Except as may be expressly permitted in your license agreement for these Programs, no part of these Programs may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose.

If the Programs are delivered to the United States Government or anyone licensing or using the Programs on behalf of the United States Government, the following notice is applicable:

U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the Programs, including documentation and technical data, shall be subject to the licensing restrictions set forth in the applicable Oracle license agreement, and, to the extent applicable, the additional rights set forth in FAR 52.227-19, Commercial Computer Software--Restricted Rights (June 1987). Oracle Corporation, 500 Oracle Parkway, Redwood City, CA 94065

The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently dangerous applications. It shall be the licensee's responsibility to take all appropriate fail-safe, backup, redundancy and other measures to ensure the safe use of such applications if the Programs are used for such purposes, and we disclaim liability for any damages caused by such use of the Programs.

Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.

The Programs may provide links to Web sites and access to content, products, and services from third parties. Oracle is not responsible for the availability of, or any content provided on, third-party Web sites. You bear all risks associated with the use of such content. If you choose to purchase any products or services from a third party, the relationship is directly between you and the third party. Oracle is not responsible for: (a) the quality of third-party products or services; or (b) fulfilling any of the terms of the agreement with the third party, including delivery of products or services and warranty obligations related to purchased products or services. Oracle is not responsible for any loss or damage of any sort that you may incur from dealing with any third party.

Optional third party notice. Third party notices are rare and must be approved by Oracle Legal. Delete the ThirdPartyNotice element if your document does not require a third party legal notice. Never add third party notice text as Para elements to existing legal notice elements. To do so will cause an archiving error.

(3)

iii

Send Us Your Comments

... ix

Preface

... xi

Intended Audience... xi

Documentation Accessibility ... xi

Structure ... xi

1 Introduction to Integration Services

Technology Requirements... 1-1

2 Architecture and Concepts

Architecture... 2-1 Concepts... 2-2

XML/HTTP-Based Interface ... 2-2 Security and Authentication... 2-2

User Management ... 2-3

Site ID... 2-3

Creating a Site... 2-3

Using a Site ID ... 2-3

Customization Using Site Properties ... 2-4

Invoking Oracle RTC Integration Services ... 2-4

3 Implementation Steps

Prerequisites... 3-1 Development Steps ... 3-1 Deployment Steps... 3-3

4 Integration Interfaces

Schedule Conference ... 4-1 Service URL... 4-1 Input Parameters ... 4-2 Return Parameters... 4-3

(4)

Error Handling ... 4-4 Update Conference... 4-4 Service URL... 4-4 Input Parameters ... 4-4 Return Parameters... 4-5 Error Handling ... 4-5 Delete Conference... 4-5 Service URL... 4-5 Input Parameters ... 4-5 Return Parameters... 4-6 Error Handling ... 4-6 Create Instant Conference... 4-6

Service URL... 4-7 Input Parameters ... 4-7 Return Parameters... 4-7 Error Handling ... 4-8 Join Conference... 4-8 Service URL... 4-8 Input Parameters ... 4-9 Return Parameters... 4-9 Error Handling ... 4-10 List Upcoming Conferences... 4-10

Service URL... 4-10

Input Parameters ... 4-10

Return Parameters... 4-11

Error Handling ... 4-12 Report Finished Conferences... 4-12

Service URL... 4-12

Input Parameters ... 4-12

Return Parameters... 4-13

Error Handling ... 4-13 Report Attendee List... 4-14

Service URL... 4-14 Input Parameters ... 4-14 Return Parameters... 4-14 Error Handling ... 4-15 Playback Conference... 4-15 Service URL... 4-15 Input Parameters ... 4-15 Return Parameters... 4-16 Error Handling ... 4-16 Errors ... 4-17

5 Sample Implementations

Live Help Flow... 5-1

Customer Perspective... 5-1

(5)

v

Live Help Application Development and Deployment ... 5-2

Live Help with Wait Page... 5-3 Web Seminar Flow... 5-5

Web Seminar Application Development Steps ... 5-5 Global Button Flow... 5-5

Global Button Application Development and Deployment ... 5-7

6 Advanced Topics

Tracking Usage... 6-1 Monitoring Meetings... 6-1 Site Customization... 6-1

A

Example Code Segment

Glossary

Index

(6)

(7)

vii

List of Figures

1–1 Centrally-Managed Oracle RTC System Supporting Multiple Lines of Business... 1-2 2–1 Oracle RTC Integration Services Architecture... 2-1 2–2 Oracle RTC System and Site Properties... 2-4 5–1 Live Help Flow: System Diagram... 5-2 5–2 Public Conferences Table... 5-3 5–3 Live Help Components ... 5-4 5–4 Global Button Flow—Host Perspective ... 5-6 5–5 Global Button Flow—Attendee Perspective ... 5-6 6–1 Oracle Web Conferencing Reports Tab ... 6-1

(8)

List of Tables

4–1 Schedule Conference Input Parameters... 4-2 4–2 Schedule Conference Return Parameters ... 4-4 4–3 Schedule Conference Errors ... 4-4 4–4 Update Conference Input Parameters ... 4-5 4–5 Update Conference Errors ... 4-5 4–6 Delete Conference Input Parameters ... 4-6 4–7 Delete Conference Return Parameters... 4-6 4–8 Delete Conference Errors ... 4-6 4–9 Create Instant Conference Input Parameters... 4-7 4–10 Create Instant Conference Return Paramters ... 4-8 4–11 Create Instant Conference Errors ... 4-8 4–12 Join Conference Input Parameters... 4-9 4–13 Join Conference Return Parameters ... 4-9 4–14 Join Conference Errors ... 4-10 4–15 List Upcoming Conferences Input Parameters... 4-11 4–16 List Upcoming Conferences Return Parameters ... 4-11 4–17 List Upcoming Conferences Conference Errors ... 4-12 4–18 Report Finished Conferences Input Parameters... 4-12 4–19 Report Finished Conferences Return Parameters ... 4-13 4–20 List Upcoming Conferences Conference Errors ... 4-13 4–21 Report Attendee List Input Parameters... 4-14 4–22 Report Attendee List Return Parameters ... 4-15 4–23 List Upcoming Conferences Conference Errors ... 4-15 4–24 Playback Conference Input Parameters... 4-16 4–25 Playback Conference Return Parameters ... 4-16 4–26 Playback Conference Errors ... 4-16 4–27 Meanings of Error Numbers ... 4-17

(9)

ix

Send Us Your Comments

Oracle Real-Time Collaboration Integration Services Guide, Release 2.0.4.3

Part No. B12158-02

Oracle welcomes your comments and suggestions on the quality and usefulness of this publication. Your input is an important part of the information used for revision.

■ Did you find any errors?

■ Is the information clearly presented?

■ Do you need more information? If so, where?

■ Are the examples correct? Do you need more examples? ■ What features did you like most about this manual?

If you find any errors or have any other suggestions for improvement, please indicate the title and part number of the documentation and the chapter, section, and page number (if available). You can send comments to us in the following ways:

■ Electronic mail: [email protected]

■ FAX: 650-506-7415. Attn: Oracle Real-Time Collaboration Documentation ■ Postal service:

Oracle Corporation

Oracle Real-Time Collaboration Documentation 500 Oracle Parkway, Mailstop 2op745

Redwood Shores, CA 94065 United States

If you would like a reply, please give your name, address, telephone number, and electronic mail address (optional).

If you have problems with the software, please contact your local Oracle Support Services.

(10)

(11)

xi

Preface

Intended Audience

This manual is intended for application developers, system administrators, and consultants.

Documentation Accessibility

Our goal is to make Oracle products, services, and supporting documentation accessible, with good usability, to the disabled community. To that end, our

documentation includes features that make information available to users of assistive technology. This documentation is available in HTML format, and contains markup to facilitate access by the disabled community. Standards will continue to evolve over time, and Oracle is actively engaged with other market-leading technology vendors to address technical obstacles so that our documentation can be accessible to all of our customers. For additional information, visit the Oracle Accessibility Program Web site at

http://www.oracle.com/accessibility/

Accessibility of Code Examples in Documentation JAWS, a Windows screen reader, may not always correctly read the code examples in this document. The conventions for writing code require that closing braces should appear on an otherwise empty line; however, JAWS may not always read a line of text that consists solely of a bracket or brace.

Accessibility of Links to External Web Sites in Documentation This documentation may contain links to Web sites of other companies or organizations that Oracle does not own or control. Oracle neither evaluates nor makes any representations regarding the accessibility of these Web sites.

Structure

This manual contains the following chapters:

Chapter 1, "Introduction to Integration Services"

This chapter introduces Oracle Real-Time Collaboration and gives an overview of the Oracle Real-Time Collaboration Integration Services. This chapter also gives samples user flows and lists technology requirements.

(12)

Chapter 2, "Architecture and Concepts"

The chapter shows the various components that are involved in providing the integration service.

Chapter 3, "Implementation Steps"

This chapter provides step-by-step instructions on what an application developer needs to implement to integrate an application with Oracle Real-Time Collaboration. It also provides step-by-step instructions on how to deploy such an application.

Chapter 4, "Integration Interfaces"

This chapter provides the specifications for each of the Integration Services interfaces that are provided by Oracle Real-Time Collaboration.

Chapter 5, "Sample Implementations"

This chapter explains the flows in sample implementations of an application integration with Oracle Real-Time Collaboration.

Chapter 6, "Advanced Topics"

This chapter discusses reporting, monitoring, and site customizations.

Appendix A, "Example Code Segment"

This appendix contains a code sample.

Conventions

The following conventions are used in this manual:

Convention Meaning

. . .

Vertical ellipsis points in an example mean that information not directly related to the example has been omitted.

. . . Horizontal ellipsis points in statements or commands mean that parts of the statement or command not directly related to the example have been omitted

boldface text Boldface type in text indicates a term defined in the text, the glossary, or in both locations.

< > Angle brackets enclose user-supplied names.

[ ] Brackets enclose optional clauses from which you can choose one or none.

(13)

Beta Draft Introduction to Integration Services 1-1

1

Introduction to Integration Services

Oracle Real-Time Collaboration (Oracle RTC) Integration Services bring real-time collaboration within the context of the business applications in an enterprise. It can be used to meet all real-time collaboration requirements in an enterprise. The Oracle RTC system can be used to cobrowse Web documents, share desktops, conduct polls, chat, stream voice, and much more. Oracle RTC facilitates real-time collaboration using a company's corporate intranet and the public Internet.

Oracle RTC Integration Services can be used by

■ Lines of business that want to easily use real-time collaboration functionality from

within the context of their applications

■ Online e-businesses that want to quickly implement very valuable features like

live help or "shop-together" from all their sites’ Web pages

■ Help desks that want to dramatically improve customer satisfaction by providing

desktop sharing with the click of a button

■ Sales organizations that want to quickly implement a system where its sales agents

can use an existing application to provide live demonstrations of their products to their customers

■ Online learning organizations that want to enhance existing applications by

providing recorded presentations of classroom material or interactive classrooms When you integrate your organization's application with Oracle RTC, you gain real-time collaboration features from within your application and with your application context. Adding real-time online collaboration capabilities to existing applications increases productivity and user satisfaction.

Oracle RTC Integration Services provide a rich set of interfaces that any application can use to integrate, in a wide range of ways, with the Oracle RTC system. Oracle RTC Integration Services provide easy, industry-standard methods for any application to tightly integrate with the Oracle RTC deployment within an enterprise.

The Oracle RTC system has been designed to let you have a single, centrally managed Oracle RTC system, deployed in an enterprise, that provides real-time collaboration functionalty to multiple lines of business at the same time. Each line of business can determine which Oracle RTC features to expose and customize how they appear to their users. This is achieved using the Oracle RTC Integration Services and the Site support.

1.1 Technology Requirements

Oracle RTC Integration Services have been designed to use industry-standard XML messages and HTTP protocol for integration with the Oracle RTC system. The

(14)

Technology Requirements

architecture facilitates a single deployment of Oracle RTC in an enterprise to meet the requirements of all types of integrating applications. The integrating applications might not be co-located and managed by the same administrator as the Oracle RTC deployment.

This model of integration lends itself very well in situations where Web applications are located in a distributed environment and they need to expose real-time capabilities by integrating with a central deployment of Oracle RTC.

Figure 1–1 Centrally-Managed Oracle RTC System Supporting Multiple Lines of Business

Figure 1–1 illustrates how Oracle RTC integrates with other applications. The Oracle RTC servers are behind the corporate firewall. The following sites are located on the corporate intranet: Marketing, Sales, Training, Support. Through Oracle RTC

Integration Services, these sites expose Oracle RTC functionality, which is provided by the Oracle RTC servers. Wireless and mobile devices can access Oracle RTC

functionality through Oracle Application Server Wireless. The Oracle RTC servers also provide Oracle Web Conferencing functionality, which users can access through the Oracle Web Conferencing Console.

All interfaces of Oracle RTC Integration Services are defined as Web-based services. These interfaces are implemented as a set of servlets that can be accessed using a URL. The parameters of the interfaces are sent as XML documents. These documents are sent as the payload of the HTTP request.

This integration model provides language and location independence.

Corporate Intranet Oracle RTC Servers Corporate Firewall Oracle Web Conferencing Consoles Oracle Application Server Wireless Wireless and Mobile Devices Oracle Web Conferencing Consoles Marketing Site Sales Site Training Site Support Site

(15)

Technology Requirements

Beta Draft Introduction to Integration Services 1-3

Invoking a servlet requires a client with the ability to construct and parse XML schemas and send the XML document over HTTP/S. There is no dependency on any specific XML library.

(16)

(17)

Beta Draft Architecture and Concepts 2-1

2

Architecture and Concepts

This chapter explains the architecture of Oracle Real-Time Collaboration (Oracle RTC) Integration Services and discusses some concepts that are essential to understanding and using them.

2.1 Architecture

Figure 2–1 Oracle RTC Integration Services Architecture

Figure 2–1 shows the various components that are involved in providing the integration services, along with the data flow among them.

1. Applications send XML messages over HTTP/S either from the client browser (1.a) or from the integrating application server (1.b) to the Oracle RTC system.

2. The HTTP listener (Oracle HTTP Server) on the Oracle RTC system picks up the HTTP/S request and invokes the Oracle RTC Integration Services servlet.

Integrating Application Servers http(s ) Integrating Application Clients -Browser -Native Applications -Java Applications ht tp (s ) http_(s) Bro wse_r/na tive clien ts-to_-se rve r (1._a) Serve r-to-se rver calls (1.b) Oracle RTC Business Object Oracle RTC Integration Servlet (7) (6) (6) Oracle HTTP Server (2), (3) (4) (5) Oracle RTC System

(18)

Concepts

3. Oracle RTC Integration Services authenticates the integrating application ("site") from which the request originates. It then processes the XML payload (input parameters) that are passed to the servlet as part of the HTTP request object.

4. Appropriate Oracle RTC business objects are invoked by the servlet to process the request.

5. Oracle RTC Integration Services packages the output as an XML message (or alternatively as a URL redirect) and sends it back to Oracle HTTP Server to be returned to the requesting application.

6. The requesting application receives the response as an XML message. In some cases, a URL redirect may be returned, depending upon caller preference.

7. The application processes the response and then returns the appropriate results to the user.

2.2 Concepts

The following concepts are required to fully understand and use the Oracle RTC Integration Services interface.

2.2.1 XML/HTTP-Based Interface

Oracle RTC Integration Services interfaces are industry standards-based. Each call is specified in terms of a set of a requests, a response, and an error XML message or documents. The messages are exchanged between the integrating application and the Oracle RTC system using HTTP/S. Each XML message has an XML schema (XSD) associated with it, which specifies the elements of the message and their semantics. The Oracle RTC Integration Services is invoked from any integrating application using the following URL:

http://<hostname>:<port>/imtapp/iapp/OracleRTCService?operation=<operation-name>&x mlin=<xml-document>

where operation-name is the name of the service being invoked and xml-document is the XML document that specifies the parameter values for the service.

The integrating application is free to use any tool to construct and validate the XML message using the appropriate XSD provided by the Oracle RTC system. It is also free to process the response XML message using any method. Similarly, the message can be sent to the Oracle RTC system using HTTP/S protocol using any standards-based HTTP library, using any programming language.

2.3 Security and Authentication

When any integrating application invokes a service provided by Oracle RTC, the integrating application (or site, as it is sometimes called) needs to be authenticated as a valid site that is authorized to invoke the Oracle RTC functionality.

Therefore, each Oracle RTC Integration Services request must be accompanied by an application identifier, or site ID, and an authentication token (AuthToken) that is specific to the integrating application. This identifier and authentication token are generated when the integrating application registers with Oracle RTC as a site that intends to integrate with it. See Section 2.3.2, "Site ID" for details on site management. The site ID and authentication token are passed as an HTTP cookie along with each request. The two fields are first concatenated with a ":" separator and then encoded

(19)

Security and Authentication

using Base64 encoding. This encoded string is then set in the HTTP header as a cookie. The name of the cookie is siteauthkey.

2.3.1 User Management

Oracle RTC uses standards based LDAP store (Oracle Internet Directory) as the source of users. When Oracle RTC is deployed, it is configured with a particular instance of an LDAP store. This directory determines the Oracle RTC user community.

Users of integrating applications fall into the following two categories:

■ Same user address space as Oracle RTC ■ Different user address space from Oracle RTC

Applications that share the same user address space can maintain their users' identity in Oracle RTC.

Applications that do not share the same address space have to create one or more proxy users. That is, they must use a common Oracle RTC account (proxy account) or a set of accounts for all users of the integrating application. The proxy account acts as a proxy for the real user.

2.3.2 Site ID

In an enterprise, a single deployment of the Oracle RTC system can be used by various line-of-business (LOB) applications. These integrating applications are called sites. An identifier for such an integrating application is called a site ID.

The Oracle RTC system uses the concept of site to provide site-level customization of the Oracle RTC deployment. The site ID is also used for authenticating a site when an application belonging to the site invokes Oracle RTC Integration Services.

2.3.2.1 Creating a Site

In order to integrate an application with the Oracle RTC system, you must create a site and site ID for it on the Oracle RTC system. This is done in the Oracle Web

Conferencing Application Site tab. After creating a site, you can set up site-specific properties to control the interaction of the site with Oracle RTC.

2.3.2.2 Using a Site ID

Applications in an enterprise can integrate with Oracle RTC in two ways:

■ tight integration: They can programmatically invoke Oracle RTC functionality

using the integration services, or

■ loose integration: If the application has a browser-based interface, they can invoke

the Oracle RTC application pages directly as URL links to these pages. In either case, the site ID is required to provide identification and authentication. For Oracle RTC service calls, the site ID is passed as one of HTTP header fields in the HTTP request to invoke the service.

Web pages that provide a link to Oracle Web Conferencing application page can provide the site ID as a URL parameter. This provides customization for that site. For example, the following URL can be used to provide a customized view of Oracle Web Conferencing for site 123456.

See Also: The Oracle Web Conferencing Administrator’s Guide and the Oracle Web Conferencing online help.

(20)

http://<hostname>:<port no>/imtapp/app/prelogin.uix?siteID=123456

Invoking this URL returns a page that has the look, feel, and contents specified for site 123456. Also, any conferences created from the application pages have the attributes defined for conferences for that site.

2.3.2.3 Customization Using Site Properties

Once a site ID is created in the Oracle RTC system, an administrator can set different site-level properties to customize Oracle RTC behavior for that site. There are two broad classes of properties:

■ Application-level properties: Change the look and feel of the Oracle Web

Conferencing application pages. Examples of such properties are the co-branding name that appears at the top of each application page, the e-mail address of the Contact Us page, the number of rows displayed in each table in the application page, and so on.

■ Conference-level properties: Change the attributes of any conference, whether it is

invoked from the application pages or from the integration service calls. Examples of such properties include the start-up (collaboration) mode of the conference, the availability of chat during the conference, and so on.

Figure 2–2 Oracle RTC System and Site Properties

Figure 2–2 shows how the various property values in the Oracle RTC system are inherited and set. When a site is created, it inherits the default values of all the properties from the system settings. For each site, the administrator can set various conference-level and application-level properties to override the default values. For example, the default setting for the system is to set the start-up mode of each

conference to Cobrowse mode. When a site is created, this default value is inherited by that site’s conference-level property for start-up mode. The site administrator can override the default value by changing this property to Desktop Sharing mode.

2.3.3 Invoking Oracle RTC Integration Services

Oracle RTC Integration Services can be invoked from any of the following:

(21)

■ Native client ■ Browser

In some of the services, the caller can provide a choice of the format of the response. The response can be a URL redirect or an XML document. This first option can be useful when the service call is being invoked from a browser.

(22)

(23)

Beta Draft Implementation Steps 3-1

3

Implementation Steps

This chapter provides step-by-step instructions for an application developer to integrate with the Oracle Real-Time Collaboration (Oracle RTC) system. It also provides step-by-step instructions for deployment. This chapter assumes that the integrating application is a browser-based application that is being integrated with the Oracle RTC system.

3.1 Prerequisites

To use Oracle RTC Integration Services, the integrating application must have the following:

■ HTTP library. The application needs to have access to an HTTP library to send and

receive HTTP messages and set HTTP cookies.

■ XML documents processing library. The application needs to be able to parse XML

documents, and optionally validate the XML document against the corresponding Oracle RTC XSD. This can either be done using any XML processing library or implemented by the integrating application developer.

■ SSL libraries. If SSL is enabled in the Oracle RTC deployment so that all

interactions with it use SSL, then you will need SSL libraries to send and receive secure messages from Oracle RTC.

3.2 Development Steps

The following steps outline the methodology. Before you begin development you should know the following:

■ Host name and port number of the Oracle RTC deployment to be used for this

integration

■ Site ID and the site authentication key for the integrating site

The Oracle Web Conferencing administrator should be able to provide these details.

Note: Oracle RTC is language-neutral with respect to the calling application. The calling application can be written in Java, C/C++, Perl, Visual Basic, etc.

(24)

Development Steps

Step 1 Download XSDs

Determine which Oracle RTC functionality to use. Download the corresponding input, return, and error XSD files. These specify the input, return, and error XML schemas for this functionality.

The XSDs are provided as reference in Appendix A, "XML Schema Reference". They are also available in any Oracle RTC deployment at the following URL:

http://<hostname>:<port>/imtapp/iapp/samples Step 2 Collect Application Data

Depending on the Oracle RTC Integration Services that will be used, collect all the required data from the user. For a Web-based application this can be done using a Web user interface.

For example, to use the Schedule Conference service, collect all the parameters that are required for scheduling a conference using the Schedule Conference service.

Step 3 Invoke Service URL

Implement a C procedure or a Java class that processes the data collected in the

"Collect Application Data" step.

1. Create an XML message from the information using the appropriate XSD.

2. Encode the site ID and authentication key using Base64 after combining the values into a string as SiteID:AuthKey. Set the Base64 encoded string as the value of the cookie named as "siteauthkey".

3. Send the XML message to the Oracle RTC service URL.

See Appendix A, "Example Code Segment" for a sample code segment that illustrates the use of these steps. The example shows how you can use a Java method to post an XML message to the Oracle RTC service URL.

Step 4 Process the Response from the Oracle RTC System

If the response code is 0 (success), then interpret the result using the appropriate response XSD. If the response code is a non-zero value, then interpret the result using the error XSD.

For example, upon successful completion of the Schedule Meeting integration service, an XML document is returned with a response code of 0. This XML document

contains, among other things, the conference ID, the host join URL, and the attendee join URL, as specified by meetingResp.xsd.

Step 5 Return Appropriate Response to User

After processing the response from the Oracle RTC system, the appropriate data (like attendee join URL or playback URLs) should be returned to the user.

For example, in the case of Web-based application that is trying to schedule a

conference, the join URL link could be constructed and sent back to the user as part of the response page that is returned to the user.

Note: Because the Oracle RTC service URL, site ID, and site authentication token can change from development to actual deployment, Oracle Corporation recommends reading these values from a configuration file.

(25)

Deployment Steps

Beta Draft Implementation Steps 3-3

3.3 Deployment Steps

After you have implemented the integrating steps in the application, follow these steps to deploy it:

Step 1 Create a Site ID

Create a site for the integrating application in the Oracle RTC system. Users with administrative privileges on the Oracle RTC system can create a site in the Oracle Web Conferencing Application. Once a site is created, a site ID and a site authentication token (site AuthToken) are generated for that site.

The integrating application needs to know these values. These values are required to configure the integrating application to work with Oracle RTC. See the "Invoke Service URL" step in Section 3.2, "Development Steps".

Step 2 Set Conference Properties

This is an optional step.

If the integrating application needs to provide functionality to create conferences with properties that are different from the system default, then you need to change the default conference properties for the site. Users with administrative privileges on the Oracle RTC system can change properties for the site.

Step 3 Deploy the Application

Deploy the application. If the application is using a configuration file to determine the Oracle RTC service URL, site ID, and site authentication token, then modify this file to include the correct values for these fields. See the "Invoke Service URL" step in

Section 3.2, "Development Steps".

Step 4 Test and Debug the Integrated Application

Test and debug the application to see if the integrated deployment works as expected.

See Also: The Oracle Web Conferencing Administrator’s Guide and the Oracle Web Conferencing online help.

(26)

(27)

Beta Draft Integration Interfaces 4-1

4

Integration Interfaces

This chapter provides the specifications for each of the Oracle Real-Time Collaboration (Oracle RTC) Integration Services. Each integration service can be invoked using a URL. The parameters of the service are passed as an XML document that is created using the corresponding XSD provided by Oracle RTC. Each service request returns an XML document as a response. The specification for each response XML is provided using a response XSD.

The Oracle RTC service URL is always of the form:

http://<hostname>:<port

number>/imtapp/app/OracleRTCService?operation=<operation>&xmlin=<xml-document>

where hostname and portnumber refer to the host name and port where the Oracle RTC system has been deployed, operation is the Oracle RTC Integration Services operation to be performed, and xml-document is the XML document that contains all the parameters for this operation.

All Oracle RTC XSDs are specified in Appendix A, "XML Schema Reference". This chapter describes the following interfaces:

■ "Schedule Conference" on page 4-1 ■ "Update Conference" on page 4-4 ■ "Delete Conference" on page 4-5

■ "Create Instant Conference" on page 4-6 ■ "Join Conference" on page 4-8

■ "List Upcoming Conferences" on page 4-10 ■ "Report Finished Conferences" on page 4-12 ■ "Report Attendee List" on page 4-14

■ "Playback Conference" on page 4-15

4.1 Schedule Conference

This service call allows an integrating application to schedule a conference on the Oracle RTC system.

4.1.1 Service URL

(28)

Schedule Conference

4.1.2 Input Parameters

The parameter "xmlin" is the XML document that contains all the input parameters for the service. This document should be based on the following XML schema:

http://<hostname>:<portnumber>/imtapp/app/scheduleMtgReq.xsd

Table 4–1, " Schedule Conference Input Parameters" describes each of the elements in the XML schema.

Table 4–1 Schedule Conference Input Parameters XML

Schema

Element Required? Data Type Valid Values Description

attendee No Conference attendee

(attendee) x-oracle-guid

No String Attendee GUID, if available. This is the

attendee’s internal ID as generated by Oracle Internet Directory.

(attendee) x-oracle-user id

No String If GUID is not available, specify the Attendee

user ID (the attendee should be a registered user in this case).

(attendee) cn

No String Display name of the attendee. This can be

specified if the GUID or the user ID is not available.

description No String Description of the conference or the conference

agenda.

dtstart Yes Time in iCal

Datetime format.

Conference start time in iCal Datetime format: YYYYMMDDTHHMMSSZ letter T is mandatory. Letter Z is optional.

dtend Yes Time in iCal

Datetime format.

Conference end time in iCal datetime format.

organizer Yes Host/organizer of the conference

(organizer) x-oracle-guid No, if x-oracle-user id is provided

String Organizer (host) GUID, if available. This is the

user’s internal ID as generated by Oracle Internet Directory. In the case of a

"SCHEDULED" conference, this also becomes the host information. Either the user repository between the integrating application and Oracle RTC must be same (Oracle RTC uses Oracle Internet Directory/Oracle Application Server Single Sign-On for user management), or the user used to log in and communicate with Oracle RTC must be specifically registered against the Oracle Internet Directory used by Oracle RTC. (organizer) x-oracle-user id Yes, if x-oracle-guid is not provided

String If GUID is not available, specify the host user ID

summary No String Conference title

x-oracle-rtc-s iteid

Yes String As specified

by Oracle RTC for this integrating application

This ID is generated by Oracle RTC and given to each site created for an integrating application. This number is unique to each integrating application and does not change. See "Create a

Site ID" on page 3-3 and the Oracle Web

(29)

Schedule Conference

4.1.3 Return Parameters

If there are no errors, the response is an XML document based on meetingResp.xsd.

http://<hostname:portnumber>/imtapp/app/meetingResp.xsd

x-oracle-rtc-p assword

No String Any string Password for this conference. If one is provided, each attendee has to provide this while joining the conference. (It is included in the e-mail invite sent to the attendees) It is also attached in the join conference URL.

x-oracle-rtc-meetingtype

No String SCHEDULED At present there is only one value possible:

SCHEDULED. The user who creates the conference is also the host of the conference. The host of a conference has complete control both for the creation/update/delete, as well as when the conference is held online.

x-oracle-rtc-s ecuritytype

No String RESTRICTED,

REGULAR, PUBLIC

Restricted - Only invited registered users can attend this conference.

Regular - Anyone who knows the conference ID and password (if one was created for this conference) can attend this conference.

Public - Same as regular except this conference is also listed in the Oracle RTC application pages under public conferences, including the prelogin page.

x-oracle-rtc-p ublishattend ees

No Boolean Whether invited users can see list of people

invited to this conference.

x-oracle-rtc-d ialininfo

No String This information will be published with the

conference details. It is a free flow text field that can contain phone number/instructions for dialing in for the attendees, etc. This is included in the e-mail invitation. This field is not interpreted by Oracle RTC in any way. x-oracle-rtc-e

nabledirectjoi n

No Boolean Whether attendees can join directly from the

e-mail link or they land up on a conference details page.

x-oracle-rtc-s endemailnoti fication

No Boolean No Whether to send an e-mail notification of the

conference creation with the join conference URL.

x-oracle-rtc-v ersion

No String Version# of this XML schema.

x-oracle-rtc-u serattr

No String Oracle RTC provides up to five attributes that

can be specified by integrating applications and will be stored with the conference information in the Oracle RTC system. Oracle RTC does not interpret these values but will return it to the integrating application as name/value pairs. Examples of uses of these are integration applications' conference ID.

Table 4–1 (Cont.) Schedule Conference Input Parameters XML

Schema

(30)

Update Conference

4.1.4 Error Handling

If there is any error (response code is non-zero), the response to the call is an XML document based on errorMsg.xsd.

http://<hostname>:<port number>/imtapp/app/errorMsg.xsd

4.2 Update Conference

This service call allows an integrating application to update an existing conference on the Oracle RTC system.

4.2.1 Service URL

number>/imtapp/OracleRTCService?operation=updateMeeting&xmlin=<xml-document>

4.2.2 Input Parameters

http://<hostname:port#>/imtapp/app/updateMtgReq.xsd

The XML elements in the Update Conference schema are the same as those in the Schedule Conference schema, except that the Update schema contains an additional element called x-oracle-rtc-meetingid. You can update any of the elements in the Update Conference schema except this meetingid element.

Table 4–2 Schedule Conference Return Parameters

XML Schema Element Required? Data Type Description

responseCode Yes Integer Return code is always 0 when executed successfully.

mtgId Yes String ID of the scheduled conference

hostURL Yes Any URL URL to be used by the host for joining the conference.

attendeeURL Yes Any URL URL to be used by any attendee for joining the

conference.

Table 4–3 Schedule Conference Errors

XML Schema Element Required? Data Type Description

responseCode Yes Integer Return code is always 0 when executed successfully

message Yes String A short description of the error

Note: The XSD for the error message is the same for all the Oracle RTC Integration Services functions. A listing of all the response codes along with a short description is available in Section 4.10, "Errors"

(31)

Delete Conference

4.2.3 Return Parameters

On successful execution, the response is an XML document whose schema is defined by meetingResp.xsd . See Section 4.1.3, "Return Parameters" for a description of the elements.

4.2.4 Error Handling

4.3 Delete Conference

This service call allows an integrating application to delete an existing conference on the Oracle RTC system.

4.3.1 Service URL

number>/imtapp/OracleRTCService?operation=deleteMeeting&xmlin=<xml-document>

4.3.2 Input Parameters

http://<hostname>:<portnumber>/imtapp/app/deleteMtgReq.xsd

Table 4–6, " Delete Conference Input Parameters" describes each of the elements in the XML schema.

Table 4–4 Update Conference Input Parameters

XML Schema Element Required? Datatype Valid values Description

x-oracle-rtc-meetingid Yes Integer ID of the

conference being updated

A unique ID generated by Oracle RTC during conference creation.

Table 4–5 Update Conference Errors

XML Schema Element Required? Data Type Description

responseCode Yes Integer Return code is always 0 on successful execution

Note: The XSD for the error message is same for all the Oracle RTC Integration Services functions. A listing of all the response codes along with a short description is available in Section 4.10, "Errors".

(32)

Create Instant Conference

4.3.3 Return Parameters

On successful execution, the response to the deleteMeeting service call is an XML document whose schema is defined by meetingResp.xsd

http://<hostname>:<portnumber>/imtapp/app/meetingResp.xsd

4.3.4 Error Handling

4.4 Create Instant Conference

This function provides the ability for an integrating application to create an instant conference and return a join URL for the host to join the conference. This service is useful when implementing a live help type of flow. The difference between this and the Schedule Conference service is that in Create Instant Conference service the conference is scheduled and started instantly.

Table 4–6 Delete Conference Input Parameters

meetingid Yes Integer ID of the conference being deleted. It is a unique ID

generated by Oracle RTC during conference creation.

siteid Yes String This ID is generated by Oracle RTC and given to each

site created for an integrating application. This number is unique to each integrating application and does not change. See "Create a Site ID" on page 3-3 and the Oracle Web Conferencing Administrator’s Guide for details.

Table 4–7 Delete Conference Return Parameters

responseCode Yes Integer Return code is always 0 on successful execution.

mtgId Yes String ID of the conference being deleted

hostURL Yes Any URL Not applicable

attendeeURL Yes Any URL Not applicable

Table 4–8 Delete Conference Errors

Note: The XSD for the error message is same for all the Oracle RTC Integration Services functions. A listing of all the response codes along with a short description is available in Section 4.10, "Errors"

(33)

Create Instant Conference

4.4.1 Service URL

http://<hostname>:<portnumber>/imtapp/app/OracleRTCService?operation=instantMeeting&xmlin=<xml -document>

4.4.2 Input Parameters

http://<hostname>:<port number>/imtapp/app/instantMtgReq.xsd

The following table describes each of the elements in the XML schema.

4.4.3 Return Parameters

The format of the return document depends on the returnType parameter.

If the returnType parameter is XML, then upon successful execution, the response is an XML document whose schema is defined by meetingResp.xsd .

Table 4–9 Create Instant Conference Input Parameters

XML Schema Element Required? Data Type Valid Values Description

meetingType No String For future use

siteid Yes String As specified

by Oracle RTC for this integrating application

This ID is generated by Oracle RTC and given to each site created for an integrating application. This number is unique to each integrating application and does not change. See "Create a Site

ID" on page 3-3 and the Oracle Web

Conferencing Administrator’s Guide for details.

password No String Conference password, if any.

meetingTitle No String The name of the conference being

scheduled.

hostExitURL No URL Valid URL The URL of the page that pops-up on

the host side after a conference has ended. This feature can be used to collect feedback/exit surveys related to the conference. This is optional.

attendeeExitURL No URI Valid URL The URL of the page that pops-up on

the attendee side after a conference has ended. This feature can be used to collect feedback/exit surveys related to the conference. This is optional.

attendeeStartURL No URI Valid URL The URL of the page that pop-up on the

attendee side when the attendee joins a conference. This feature can be used to lead the attendee to some informational page about the conference. Example, sales related page in a sales conference. This is optional.

returnType No String XML, text When return type is set to XML, an

XML document is returned. When return type is set to text, then the return type is a URL redirect.

(34)

Join Conference

http://<hostname>:<portnumber>/imtapp/app/meetingResp.xsd

If the returnType is text, then the join conference URL is returned with the redirect header. This is useful when the Create Instant Conference service is called from a browser window. In this case, the browser window is automatically redirected to the URL location, which automatically launches the Oracle Web Conferencing Console to start the Web conference.

4.4.4 Error Handling

The format of the error document depends on the returnType parameter. If the returnType is text, then the appropriate error message is returned as a text/HTML page.

If the returnType is XML, if there is any error (response code is non-zero), the response to the call is an XML document based on errorMsg.xsd.

4.5 Join Conference

The Join Conference service enables a user who has the conference ID to join a Web conference.

4.5.1 Service URL

http://<hostname>:<portnumber>/imtapp/OracleRTCService?operation=joinMeeting&xmlin=<xml-docum ent>

Table 4–10 Create Instant Conference Return Paramters

hostURL Yes Any URL URL to be used by the host for joining the

conference

Table 4–11 Create Instant Conference Errors

responseCode Yes Integer Return code is always 0 upon successful execution

(35)

Join Conference

4.5.2 Input Parameters

http://<hostname>:<port number>/imtapp/app/joinMtgReq.xsd

Table 4–12, " Join Conference Input Parameters" describes each of the elements in the XML schema.

4.5.3 Return Parameters

If the returnType parameter is XML, then on successful execution, the response is an XML document whose schema is defined by meetingResp.xsd .

http://<hostname>:<portnumber>/imtapp/app/meetingResp.xsd

If the returnType is text, then the join conference URL is returned with redirect header. This is useful when the Join Conference service is called from a browser window. In this case the browser window is automatically redirected to the URL location, which

Table 4–12 Join Conference Input Parameters XML Schema

Element Required? Data Type Valid Values Description

meetingid Yes Integer ID of the

conference to be joined

siteid Yes String As specified by

Oracle RTC for this integrating application

This ID is generated by Oracle RTC and given to each site created for an integrating

application. This number is unique to each integrating application and does not change. See "Create a Site ID" on page 3-3 and the Oracle Web Conferencing Administrator’s Guide for details.

password No String The conference

key created by the host

Conference key, if any.

firstName No String Any string First name of the person joining.

lastName No String Any string Last name of the person joining.

emailAddress No String Any email

address

Email address of the person joining.

returnType No String XML, text The format of the return value: XML document

or URL redirect. Default is XML.

Table 4–13 Join Conference Return Parameters

responseCode Yes Integer Return code is always 0 upon successful execution.

hostURL Yes Any URL URL to be used by the host for joining the conference

(36)

List Upcoming Conferences

automatically launches the Oracle Web Conferencing Console to start the Web conference.

4.5.4 Error Handling

The format of the error document depends on the returnType parameter. If the returnType is text, then the appropriate error message is returned as a text/HTML page.

If the returnType is XML, if there is any error (response code is non-zero), the response to the call is an XML document based on errorMsg.xsd.

4.6 List Upcoming Conferences

The List Upcoming Conferences service allows an integrating application to list upcoming conferences for a particular user or list all upcoming public conferences.

4.6.1 Service URL

http://<hostname:portnum>/imtapp/iMeetingService?operation=listUpcomingConfs&xmlin=xml-documen t

4.6.2 Input Parameters

http://<hostname>:<port number>/imtapp/app/listUpcomingConfsReq.xsd

Table 4–15, " List Upcoming Conferences Input Parameters" describes each of the elements in the XML schema.

If no userGUID is specified, upcoming conferences for all users will be returned. If no meetingType is specified, conferences of all types will be returned. For example, if you specify a userGUID and no meetingType, the list of meetings returned should match the "My Upcoming Meetings" table in the application.

Table 4–14 Join Conference Errors

responseCode Yes Integer Return code is always 0 upon successful execution

(37)

List Upcoming Conferences

4.6.3 Return Parameters

If the returnType parameter is XML, then on successful execution, the response is an XML document whose schema is defined by listUpcomingConfsResp.xsd.

http://<hostname:port#>/imtapp/app/jlistUpcomingConfsResp.xsd

Table 4–15 List Upcoming Conferences Input Parameters XML Schema

siteID Yes Integer As specified by

This ID is generated by Oracle RTC and given to each site created for an integrating application. This number is unique to each integrating application and does not change. See "Create a Site ID" on page 3-3 and the Oracle Web Conferencing Administrator’s Guide for details.

userGUID No String GUID of the host (the user who scheduled

the conference), if available. This is the internal ID as generated by Oracle Internet Directory.

meetingType No String Restricted,

Regular, or Public

Restricted - Only invited registered users can attend this conference.

Regular - Anyone who knows the conference ID and password (if one was created for this conference) can attend this conference. Public - Same as regular except this conference is also listed in the Oracle RTC application pages under public conferences, including the prelogin page.

returnType No String XML, text The format of the return value: XML

document or URL redirect. Default is XML.

Table 4–16 List Upcoming Conferences Return Parameters

XML Schema Element Required? Data Type Description

meetingID Yes String ID of the scheduled conference. It is a unique ID generated

by Oracle RTC during conference creation.

title Yes String The Conference ID assigned by the host when scheduling

the conference.

hostName Yes String User name of the host who scheduled the conference.

hostUserGUID Yes String GUID of the host who scheduled the conference, if

available. The GUID is generated by Oracle Internet Directory.

scheduledStartTime Yes Long Start time of the conference in Universal Time Code (UTC) format.

meetingStatus Yes String Any of the following: Not Started, Waiting for Host, or In Progress.

meetingType Yes String The type of meeting: Restricted, Regular, or Public

(38)

Report Finished Conferences

4.6.4 Error Handling

4.7 Report Finished Conferences

The Report Finished Conferences service allows an integrating application to list finished conferences.

4.7.1 Service URL

http://<hostname:portnum>/imtapp/iMeetingService?operation=reportFinishedConfs&xmlin=xml-docum ent

4.7.2 Input Parameters

http://<hostname>:<port number>/imtapp/app/reportFinishedConfs.xsd

Table 4–18, " Report Finished Conferences Input Parameters" describes each of the elements in the XML schema.

Table 4–17 List Upcoming Conferences Conference Errors

Table 4–18 Report Finished Conferences Input Parameters XML Schema

siteID Yes Integer As specified by

This ID is generated by Oracle RTC and given to each site created for an integrating application. This number is unique to each integrating application and does not change. See "Create a Site ID" on on page 3-3 and the Oracle Web Conferencing Administrator’s Guide for details.

startDate Yes dateTime Any valid date

and time in the format shown at right

Start date for this report. All conferences starting between the start and end date values (including the start and end dates) are included. Format: yyyy-MM-dd’T’hh:mm:ss

(39)

Report Finished Conferences

4.7.3 Return Parameters

If the returnType parameter is XML, then on successful execution, the response is an XML document whose schema is defined by the following XSD:

http://<hostname:port#>/imtapp/app/jreportFinishedConfsResp.xsd

4.7.4 Error Handling

endDate Yes dateTime Any valid date

and time in the format shown at right

End date for this report. All conferences starting between the start and end date values (including the start and end dates) are included. Format: yyyy-MM-dd’T’hh:mm:ss

includeAttendees No Boolean true (include) or

false (exclude)

Include or exclude the list of attendees for each conference.

document or URL redirect. Default is XML.

Table 4–19 Report Finished Conferences Return Parameters

conferenceID Yes String ID of the scheduled conference.

title Yes String The Conference ID assigned by the host when scheduling

the conference.

hostName Yes String User name of the host who scheduled the conference.

startTime Yes Long Start time of the conference in Universal Time Code (UTC)

format.

duration Yes Integer Duration of the conference in minutes.

attendees Yes Integer Number of attendees.

rating Yes String Average rating given by attendees to this conference:

Excellent, Good, or Poor.

comments Yes String Any comments given by attendees.

finishStatus Yes String Any of the following, describing how the conference was ended: graceful, aborted, abandoned, failed, or forced.

Table 4–18 (Cont.) Report Finished Conferences Input Parameters XML Schema

(40)

Report Attendee List

4.8 Report Attendee List

The Report Attendee List service allows an integrating application to list all attendees of a completed conference.

4.8.1 Service URL

http://<hostname:portnum>/imtapp/iMeetingService?operation=reportAttendeeList&xmlin=xml-documen t

4.8.2 Input Parameters

http://<hostname>:<port number>/imtapp/app/reportAttList.xsd

Table 4–21, " Report Attendee List Input Parameters" describes each of the elements in the XML schema.

4.8.3 Return Parameters

If the returnType parameter is XML, then on successful execution, the response is an XML document whose schema is defined by the following XSD:

http://<hostname:port#>/imtapp/app/jreportAttListResp.xsd

Table 4–21 Report Attendee List Input Parameters XML Schema

meetingID Yes String ID of the

scheduled conference

siteID Yes String As specified by

This ID is generated by Oracle RTC and given to each site created for an integrating application. This number is unique to each integrating application and does not change. See "Create a Site ID" on on page 3-3 and the Oracle Web Conferencing Administrator’s Guide for details.

(41)

Playback Conference

4.8.4 Error Handling

4.9 Playback Conference

The Playback Conference service allows applications to retrieve a playback URL of any conference that has been recorded and published by the host.

4.9.1 Service URL

http://<hostname>:<portnumber>/imtapp/OracleRTCService?operation=playback&xmlin=<xml-document >

4.9.2 Input Parameters

http://<hostname>:<port number>/imtapp/app/playbackReq.xsd

Table 4–24, " Playback Conference Input Parameters" describes each of the elements in the XML schema.

Table 4–22 Report Attendee List Return Parameters

name Yes String Name of this attendee.

emailAddress Yes String Attendee’s email (if available).

timeEntered Yes Long Time at which this attendee entered the conference in

Universal Time Code (UTC) format.

timeExited Yes Long Time at which this attendee left the conference in Universal

Time Code (UTC) format.

guest Yes Boolean Whether this attendee is a registered user (No) or a guest

user (Yes).

Oracle Real-Time Collaboration