../E63259-01.epub /> ../E63259-01.mobi />

48 Integrating Events

This chapter explains how to integrate events functionality into a WebCenter Framework application at design time.

This chapter includes the following sections

For information about managing and including events, see:

48.1 Introduction to Events

In Portal Framework applications, events provide access to your personal Microsoft Exchange calendar.

This section includes to following subsections:

48.1.1 Understanding Events

With events, users can:

  • Display their Microsoft Exchange calendars in the application.

  • Create, edit, and delete events in their Exchange calendars.

  • Change the view of the Events task flow to view calendar events by month, week, or day, or as a list.

  • Personalize the Events task flow to display events based on the start time, secondary time zone, list type, and list count

Events is integrated with many WebCenter Portal tools and components, such as links, mail, and search.

Figure 48-1 shows an example of a personal calendar in a Framework application.

Figure 48-1 Personal Calendar

Description of Figure 48-1 follows
Description of "Figure 48-1 Personal Calendar"

48.1.2 Requirements for Events

Events integrates with Microsoft Exchange Server to provide access to personal calendars. You must install and configure the appropriate server.

For information about installing and configuring Exchange Server, see "Events Prerequisites for Personal Events" in the Oracle Fusion Middleware Administering Oracle WebCenter Portal.

48.1.3 What Happens at Runtime

At runtime, users can view events from their Microsoft Exchange calendars.

For more information about events at runtime, see the chapter "Working with Events" in the Oracle Fusion Middleware Using Oracle WebCenter Portal.

Note:

Oracle Fusion Middleware Using Oracle WebCenter Portal discusses both personal events and portal events. Only the information on personal events applies to Portal Framework applications.

48.2 Basic Configuration for Events

This section includes the following subsections:

48.2.1 Configuration Roadmap for Events

The flow chart (Figure 48-2) and table (Table 48-1) in this section provide an overview of the prerequisites and tasks required to get events working in Framework applications.

Figure 48-2 Configuring Events for Portal Framework Applications

Description of Figure 48-2 follows Use MS Exchange Server 2007 Use MS Exchange Server 2003 Configure MS Exchange Server 2007 Edit security settings (Optional) Enable SSL Download and install WebCenter Portal's Personal Events Web Service Plug-in Configure MS Exchange 2003 Configure a connection to the events server in JDeveloper Add an Events task flow to a page in JDeveloper Use JDeveloper Use Fusion Middleware Control Use WLST Use WLS Admin Console Use JDeveloper, then redeploy the application Use Fusion Middleware Control Use WLST Access personal calendar Default
Description of "Figure 48-2 Configuring Events for Portal Framework Applications"

Table 48-1 Configuring Events for Portal Framework Applications

Actor Task Sub-task Notes

Administrator

1. Install WebCenter Portal and Microsoft Exchange Server

  

MS Exchange Server is the back-end server for personal calendars
 

1.a Configure MS Exchange Server 2007

1.b Edit security settings

1.c (Optional) Enable SSL

  
 

1.a Download and install WebCenter Portal's Personal Events Web Service Plug-in

1.b Configure MS Exchange Server 2003

1.c (Optional) Enable SSL

  

Developer

2. Integrate events in your application

2.a Configure a connection to the events server in JDeveloper

2.b Add an Events task flow to a page in JDeveloper

  

Developer/

Administrator

3. Deploy the application using one of the following tools:

    

Developer/

Administrator

4. Add/modify connection parameters using one of the following tools:

    

End User

5. Access personal calendar

  

Click Login to Personal Calendar on the Events task flow and enter your MS Exchange login credentials

48.2.2 Setting Up a Connection for Events

To take advantage of events functionality, you must first create a connection to the Exchange server from your Framework application. To do this, ensure that you have the connection information for the server.

You can register several server connections for events, but only one connection is active at a time.

Note:

While you can set up the connections to back-end servers at design time in JDeveloper, you can later add, delete, or modify connections in your deployed environment using Enterprise Manager Fusion Middleware Control. For more information, see the section "Registering Events Servers Using Fusion Middleware Control" in the Oracle Fusion Middleware Administering Oracle WebCenter Portal.

To set up a connection for events:

  1. In JDeveloper, open the application in which you plan to consume events.

  2. To create a connection that is available to all applications, in the Resource Palette, click the New icon and choose New Connection and then WebCenter Personal Event Connection.

    To create a connection that is available to the current application only, in the Application Resources panel of the Application Navigator, right-click Connections and choose New Connection and then WebCenter Personal Event Connection.

  3. In the Create Events Connection dialog, in the Connection Name field, enter a meaningful name, for example ExchangeServerForEvents (Figure 48-3).

    Figure 48-3 Create Events Connection Dialog

    Description of Figure 48-3 follows
    Description of "Figure 48-3 Create Events Connection Dialog"

  4. In the Web Service URL field, enter the URL of the web service exposing the event application. Use the format:

    protocol://host:port/appWebServiceInterface/WSName

    For example:

    http://myexchange.com:80/ExchangeWS/PersonalEventsWebService.asmx
http://myexchange.com:80/EWS/Services.wsdl

  5. From the Service Adapter dropdown list, select the version of the Microsoft Exchange server to connect to:

    • MSExchange2003

    • MSExchange2007

  6. Select Default Connection to use this connection for events. You can have multiple connections, but only one can be active (default).

    Note:

    After you create a connection as the active connection, you cannot edit it so that it is not the default. To use a different active connection, you must create a new connection and mark that as the default connection.

  7. Click Test Connection, and if it is successful, then click OK.

    If the test is not successful, check the settings and try again.

  8. If you created the connection in the Resource Palette, you must add it to the application.

    In the Resource Palette, under IDE Connections, right-click the connection and choose Add to Application.

    The connection is listed in the Application Resources panel of the Application Navigator (Figure 48-4). An external application connection is also created to store the user names and passwords of users who connect to the Exchange server.

    Figure 48-4 Application Resources - Personal Event Connection

    Description of Figure 48-4 follows
    Description of "Figure 48-4 Application Resources - Personal Event Connection"

48.2.3 Adding Events Functionality at Design Time

This section includes the following subsections:

48.2.3.1 Events Task Flows

Events task flows enable you to add a main view or quick view of events to a page.

Table 48-2 Events Task Flows

Task Flow Description

Calendar Main View

This task flow displays a calendar of events and provides users with options to view events in day, week, month, or list view.

Calendar Mini View

This task flow displays a calendar, similar to Calendar Main View, however, it requires less space. Only users with permission to edit the page and task flow can configure the event view (available in day or list view).

48.2.3.2 How to Add Events Functionality to Your Application

To add an Events task flow to your application:

  1. Follow the steps described in Section 4.2, "Preparing Your Framework Application for Tools and Services," to implement security and create a new customizable page in your application.

  2. Open the page on which you want to add the task flow.

  3. In the Resource Palette, expand My Catalogs, WebCenter Portal - Services Catalog, and Task Flows.

  4. Drag Calendar Main View or Calendar Mini View and drop it onto the page, inside the af:form tags.

  5. When prompted, select Region as the way to create the task flow.

  6. The Events task flows are contained within the event-view.jar library, so click Add Library to add the library to your project. This operation may take a moment to complete.

  7. Click OK.

  8. Save and run your page.

    Figure 48-5 shows the Calendar Main View task flow at runtime.

    Figure 48-5 Calendar Main View Task Flow

    Description of Figure 48-5 follows
    Description of "Figure 48-5 Calendar Main View Task Flow"

    Figure 48-6 shows the Calendar Mini View task flow at runtime.

    Figure 48-6 Calendar Mini View Task Flow

    Description of Figure 48-6 follows
    Description of "Figure 48-6 Calendar Mini View Task Flow"

48.2.4 Setting Security for Events

When you create the connection to the Microsoft Exchange Server for events, an external application connection is also created. This external application connection is created to store the user name and password of users in the Microsoft Exchange Server. For more information, see Section 48.2.2, "Setting Up a Connection for Events."

48.3 Using the Events REST API

WebCenter Portal provides a REST API to support events. Use the REST API to create your own interface for providing access to portal events.

Note:

The Events REST API is available for portal events only. You cannot use the REST API to work with personal events.

This section describes the REST API methods associated with events. It includes the following subsections:

48.3.1 Events Entry Point

The entry point for events can be reached only through a portal. First you need to navigate to the appropriate portal and then find the link element with a resourceType of:

urn:oracle:webcenter:events:gsEvents

The corresponding href or template element provides the URI entry point. The client sends HTTP requests to this entry point to work with events.

For more information about the Resource Index, see Section 53.5.1, "Using the Resource Index."

For more information about resource types, see Section 53.5.2.1, "Resource Type."

48.3.2 Events Resource Type Taxonomy

When the client has identified the entry point, it can then navigate through the resource type taxonomy to perform the required operations. For more information about the individual resources types, see the appropriate section in Section 48.3.4, "Events Resource Types."

The taxonomy for events is:

urn:oracle:webcenter:events:gsEvents
  urn:oracle:webcenter:events:gsEvent
urn:oracle:webcenter:events:gsCategories

48.3.3 Security Considerations

There are no specific security considerations for events. For general security considerations, see Section 53.8, "Security Considerations for WebCenter Portal REST APIs."

48.3.4 Events Resource Types

This section provides you with all the information you need to know about each resource type. It includes the following subsections:

48.3.4.1 urn:oracle:webcenter:events:gsEvents

Use this resource to identify the URI to use to retrieve (GET) and create (POST) portal events. The response from a GET operation includes each portal event in this collection of events, and each event includes links used to operate on that event. The response from a POST operation includes the event that was created in this collection of events and a link to operate on that event.

Navigation Paths to gsEvents

This section shows how the client can navigate through the hypermedia to access this resource:

resourceIndex
   spaces
      gsEvents

Supported Methods for gsEvents

The following methods are supported by this resource:

  • GET

    • request - body: <gsCategory>, Parameters: startIndex, itemsPerPage, utoken

      For information about these common parameters, see "Common Request Query Parameters".

      The following additional parameters are available:

      • startDate—the date from which to start listing portal events

      • endDate—the date at which to stop listing portal events

      For the start and end dates, use the format YYYY-MM-DD, for example 2011-09-01. You can also specify a time (for example, 2011-09-01T09:00:00) and a timezone sign (for example, for UTC, 2011-09-01T09:00:00Z).

    • response - body: 0 or more events

  • POST

    • request - body: event

    • response - body: event

Resource Types Linked to From gsEvents

Table 48-3 lists the resource types that the client can link to from this resource.

Table 48-3 Related Resource Types for gsEvents

rel resourceType

self

urn:oracle:webcenter:events:gsEvents

48.3.4.2 urn:oracle:webcenter:events:gsEvent

Use this resource type to identify the URI to use to read (GET), update (PUT), or delete (DELETE) a specific portal event. The response from a GET operation includes the specific event identified by the URI. The response from a PUT operation includes the modified version of the event identified by the URI. The response from a DELETE operation is a 204.

Navigation Paths to gsEvent

resourceIndex
   spaces
      gsEvents
         gsEvent

Supported Methods for gsEvent

The following methods are supported by this resource:

  • GET

    • request - body: none

    • response - body: event

  • PUT

    • request - body: event

    • response - body: event

  • DELETE

    • request - body: none

    • response - body: none

Writable Elements for gsEvent

Table 48-4 lists the writable elements for this resource.

Table 48-4 Writable Elements for gsEvent

Element Type Required Constraints Description

category

String

No

The name of an event category defined for the portal

The category to which the event belongs.

Note: If the category does not exist, the default is used if the event is being created. However, an error will occur if the event is being modified.

details

String

No

1 or more characters

Additional details about the event

endTime

Date

Yes

YYYY-MM-DDTHH:MM:SS

endTime must be greater than or equal to startTime

The date and time at which the event ends

location

String

No

1 or more characters

The location at which the event takes place

priority

String?

No

1 - Highest

2 - High

3 - Normal

4 - Low

5 - Lowest

The priority of the event, which determines where it appears when events clash

startTime

Date

Yes

YYYY-MM-DDTHH:MM:SS

The date and time at which the event starts

summary

String

Yes

1 or more characters

A brief description of the event to serve as the title of the event

Read-only Elements for gsEvent

Table 48-5 lists the read-only elements for this resource.

Table 48-5 Read-only Elements for gsEvent

Element Type Description

author

personReference

User who created the event

created

Date

Date on which the event was created

duration

String

The length (in minutes) of the event

groupSpace

groupSpaceReference

The portal to which the event belongs

id

String

Unique ID of the event

isAllDayEvent

Boolean

Indicates whether the event takes place over an entire day

modified

Date

Date on which the event was last updated

modifiedByUser

personReference

User who last updated the event

Resource Types Linked to from gsEvent

Table 48-6 lists the resource types that the client can link to from this resource.

Table 48-6 Related Resource Types for gsEvent

rel resourceType

self

urn:oracle:webcenter:events:gsEvent

48.3.4.3 urn:oracle:webcenter:events:gsCategories

Use this resource to identify the URI to use to retrieve (GET) and create (POST) portal event categories. The response from a GET operation includes each category in this collection of categories, and each category includes links used to operate on that category. The response from a POST operation includes the category that was created in this collection of categories and a link to operate on that category.

Navigation Paths to gsCategories

This section shows how the client can navigate through the hypermedia to access this resource:

resourceIndex
   spaces
      gsCategories

Supported Methods for gsCategories

The following methods are supported by this resource:

  • GET

    • request - body: category

    • response - body: 0 or more categories

  • POST

    • request - body: category

    • response - body: category

Resource Types Linked to From gsCategories

Table 48-7 lists the resource types that the client can link to from this resource.

Table 48-7 Related Resource Types for gsCategories

rel resourceType

self

urn:oracle:webcenter:events:gsCategories

48.4 Troubleshooting Events

This section provides information to assist you in troubleshooting problems you may encounter while using events.

Problem

Error message displayed in calendar taskflow:

Personal Events is not configured properly. Rectify the configuration and then click Try Again.

Solution

Confirm that you have created a Personal Event Connection. For more information, see Section 48.2.2, "Setting Up a Connection for Events."

Problem

After logging into the calendar with the right credentials, you continue to see the Login to Personal Calendar link rather than your events.

Solution

Confirm that the page on which calendar taskflow is added is a secured page. Anonymous users cannot log into the Personal Event Calendar server.