42 Integrating the Links Service

This chapter explains how to integrate the Links service in a WebCenter Portal application at design time.

For more information about managing and including links, see:

This chapter includes the following sections:

42.1 Introduction to the Links Service

This section provides overview information about the Links service features and requirements. It includes the following subsections:

42.1.1 Understanding the Links Service

The Links service provides a way to view, access, and associate related information. For example, in a list of project assignments, you can link to the specifications relevant to each assignment. In a discussion thread about a problem with a particular task, you can link to a document that provides a detailed description of how to perform that task.

The Links service provides a means for the application developer to set up source objects (for example, the Discussions service) and target objects (for example, a document), thus enabling your users to create links between the two objects.

There are three actions associated with the Links service: create, delete, and manage. The manage action includes the create and delete actions.

The following custom JSF components are included in the service:

  • Links Detail Button: This displays an icon and (optionally) a hyperlink that users click to open the Links Panel. To use the Links Detail Button, you must also include the Links - Dialog task flow as a region on the page.

  • Links Detail Menu Item: This adds a menu item that opens the Links Panel. You can embed this item in an ADF menu. To use the Links Detail Menu Item, you must also include the Links - Dialog task flow as a region on the page.

  • Links Status Icon: This has two versions:

    The gray Links icon (Figure 42-1) indicates that no links are present in the Links dialog.

    Figure 42-1 The Links Icon (No Links Present)

    Links icon
    Description of "Figure 42-1 The Links Icon (No Links Present)"

    The gold Links icon (Figure 42-2) indicates that links are present in the Links dialog.

    Figure 42-2 The Links Icon (Links Present)

    Links icon (links present)
    Description of "Figure 42-2 The Links Icon (Links Present)"

You can link from the following objects:

  • Announcements

  • Discussions

  • Documents

  • Events

  • Lists

  • Pages

  • Any object that has a custom JSF component (such as the Links Detail button) bound to it

You can link to the following new objects:

  • Discussions

  • Documents

  • Events

  • Notes

  • URLs

You can link to the following existing objects:

  • Announcements

  • Discussions

  • Documents

  • Events

Note:

The Lists and Notes services are available in WebCenter Spaces only.

Links are not available for the other WebCenter services, such as Mail and People Connections.

The Links service supports bidirectional links between objects. For example, when you create a link from a discussion topic to a document, a link from the document back to the discussion topic also is created. Similarly, when you delete the link from the discussion topic to a document, the link from the document back to the discussion topic is automatically deleted. Bidirectional linking is not available for URLs, notes, and specific list rows.

42.1.2 Requirements for the Links Service

Links automatically recognize any WebCenter service in your application. After you have configured a service in your application, you can add links. However, links work only on secured pages. Links icons do not appear on unsecured pages. For more information, see Section 42.2.3, "Setting Security for the Links Service."

42.1.3 What Happens at Runtime

Linking provides an easy way for you to share information with your social network. Linking can help you realize a significant reduction of wasted time and effort normally spent looking for information.

The Links service exposes its features through a Links dialog (Figure 42-3), accessible wherever the Links icon (Figure 42-1) appears in your application.

Figure 42-3 Links Dialog

Links dialog
Description of "Figure 42-3 Links Dialog"

With the Links service, you can do the following:

  • Link an object (such as a page) to an existing object (such as a discussion topic) by clicking the Link icon, selecting Link to Existing, choosing the resource Discussions. Optionally, you can choose a specific forum and click the topic title to choose a link.

  • Link an object (such as a discussion topic) to a new object (such as a new note or URL) by clicking the Link icon for discussion topic, selecting Link to New, and choosing either Note or URL.

  • Create multiple links from one object.

  • Delete a link.

For more information about the Links service at runtime, see Oracle Fusion Middleware User's Guide for Oracle WebCenter Spaces.

42.2 Basic Configuration for the Links Service

This section describes the steps required for adding the Links service to your application. It includes the following subsections:

42.2.1 Setting up Connections for the Links Service

The Links service requires a connection to the database where the WebCenter schema is installed. The link map (that is, relationship information such as what object is linked to what other object) is stored in the database.

For details about setting up a database connection, see Section 7.2.2, "Setting Up a Database Connection."

42.2.2 Adding the Links Service at Design Time

This section explains a basic incorporation of the Links service. It includes the following subsections:

42.2.2.1 Links Service Task Flows

The Links service includes one task flow: Links Dialog.

42.2.2.2 How to Add the Links Service to your Application

To add the Links Dialog task flow to your WebCenter Portal application:

  1. Follow the steps described in Chapter 3, "Preparing Your Development Environment" to create a customizable page in your application.

  2. Ensure that you have set up the database connection to a database with the WebCenter schema installed (Section 42.2.1).

  3. Open the page on which you want to add the Links service.

  4. In the Component Palette, click WebCenter Links Service.

  5. Drag and drop the Links Detail Button component onto your page inside the panelGroupLayout.

    The button is placed inside of a panelGroupLayout for the purposes of this example only. It is not required that you always place the button inside a panelGroupLayout.

  6. In the Insert Links Detail Button dialog (Figure 42-4), enter a unique object description, ID, and name.

    Figure 42-4 Insert Links Detail Button Wizard

    Description of Figure 42-4 follows
    Description of "Figure 42-4 Insert Links Detail Button Wizard"

    The properties in this dialog include:

    • objectDescription: The description of the object to which you are binding the Links Detail Button

    • objectId: A unique ID that identifies the object to which you are binding the Links Detail Button

    • objectName: The name of the object to which you are binding the Links Detail Button

    • serviceId: An application-wide ID that identifies your application

  7. In the ServiceId field, enter OnDemand.

    Note:

    The Links service combines the serviceId and objectId to uniquely identify the object to which you bind the Links Detail Button.

  8. Click OK.

    The new button displays in your page source (Figure 42-5).

    Figure 42-5 The Link Detail Button in Your Page Source

    Description of Figure 42-5 follows
    Description of "Figure 42-5 The Link Detail Button in Your Page Source"

  9. In the Resource Palette, open My Catalogs, then open the Task Flows folder.

  10. Drag and drop the Links Dialog task flow next to the Link Detail button on your page, and select Region from the context menu.

  11. Save and run your page to the browser.

42.2.3 Setting Security for the Links Service

The Links service requires secured pages. Links icons do not appear on unsecured pages.

ADF security is configured by default if you created your application using the WebCenter Portal Application template. For information about configuring ADF security, see Section 67.3, "Configuring ADF Security."

42.2.4 Troubleshooting the Links Service

This section describes common problems and solutions for the Links service.

Problem

The Links icon does not appear.

Solution

The Links service requires a database connection to the WebCenter schema, where links information is stored. Make sure that you have created the connection to the database and made it available in the Application Resources panel of the Application Navigator. If the connection is available in the Resource Palette but not in Application Resources, then simply drag the connection from the Resource Palette to the Connections folder in Application Resources.

Problem

Existing links appear, but you are not able to create new links or delete existing links.

Solution

The RelationshipPermission permission is automatically granted to authorized users when a service is consumed. Verify that this permission has been granted. For information, see Section 67.3.2, "Automated Security Grants for WebCenter Services."

42.3 Advanced Information for the Links Service

This section describes optional features available with this service. It includes the following subsection:

42.3.1 Using the Links Service REST APIs

Oracle WebCenter provides REST APIs to support the Links service. Use the Links service REST APIs to post links between two objects. For example, you could create a link between an event and a document in a Space.

This section describes the REST APIs associated with the Links service. It includes the following subsections:

For an introduction to the REST APIs, see Chapter 55, "Using Oracle WebCenter REST APIs."

Note:

REST APIs do not work out of the box. Before you can use REST APIs, you must take the configuration steps outlined in the following section: Section 55.2, "Before You Begin: Performing Required Configurations."

42.3.1.1 Links Entry Point

Each REST service has a link element within the resource index that provides the entry point for that service. To find the entry point for the Links service, find the link element with a resourceType of:

urn:oracle:webcenter:links

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

For more information about the resource index, see Section 55.6.1, "The Resource Index."

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

42.3.1.2 Links Resource Type Taxonomy

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

The taxonomy for the Links service is:

urn:oracle:webcenter:links
   urn:oracle:webcenter:links:results

Beyond the service entry points, URL templates allow clients to pass query parameters to customize their requests and control the form of returned data.

42.3.1.3 Security Considerations

Authentication is required before using Links REST API methods.

For general security considerations, see Section 55.9, "Security Considerations for WebCenter REST APIs."

42.3.1.4 Links Resource Types

This section provides information about each resource type. It includes the following subsection:

42.3.1.4.1 urn:oracle:webcenter:links:results

Use this resource type to identify the URI to use to create (POST) a link between two objects

The request is represented by the URL, and the response is a link, each with metadata to help the end user choose an item to drill down and cross links to the owning REST services, if available. If the owning REST service is unavailable, then an HREF link is provided.

Navigation Paths to results

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

resourceindex
   links
      results

resourceindex
   spaces
      spaces:resourceindex
         spaces:links
            results

Supported Methods for results

The following method is supported by this resource:

  • POST

    • request - body: a source and a target object, each of which has a serviceId, resourceId, and resourceName; if the target is a URL link, then the target object also contains a resourceUrl, Parameters: serviceId, resourceId, resourceName

    • response - body: Status of "204 No Content" if successful, or "403 Forbidden" if the user has no permission to create a link

where:

  • serviceId={serviceId}

    Optional: The service ID of the item, such as services.oracle.webcenter.collab.calendar.community

  • resourceId={resourceId}

    The resource ID, such as s833cddc4_caa5_416c_87e9_d702ef870b43;;3b0c6edb

  • resourceName={resourceName}

    The resource name, such as New Event.

For more information, see Section 55.6.2.5, "Templates."

Resource Types Linked to From results

Table 42-1 lists the resource types that the client can link to from this resource.

Table 42-1 Related Resource Types for links

rel resourceType

self

urn:oracle:webcenter:links:results