22 Integrating the Links Service

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

For more information about managing and including links, see:

"Setting up the WebCenter Repository" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter
"Working with the Links Service" in the Oracle Fusion Middleware User's Guide for Oracle WebCenter

This chapter includes the following sections:

Section 22.1, "Introduction to the Links Service"
Section 22.2, "Basic Configuration for the Links Service"

22.1 Introduction to the Links Service

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

Section 22.1.1, "Understanding the Links Service"
Section 22.1.2, "Requirements for the Links Service"
Section 22.1.3, "What Happens at Runtime"

22.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 22-1) indicates that no links are present in the Links dialog.

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

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

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

Figure 22-2 The Links Icon (Links Present)

Description of "Figure 22-2 The Links Icon (Links Present)"

You can lin k 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

Links are not available for the following WebCenter services:

Mail
People Connections
Worklist
Search

The Links ser vice 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.

Note:

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

22.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 22.2.3, "Setting Security for the Links Service."

22.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 22-3), accessible wherever the Links icon (Figure 22-1) appears in your application.

Figure 22-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.

Note:

You can see the Links service in action in the sample application, as described in Chapter 2, "Introduction to the WebCenter Sample Application."

22.2 Basic Configuration for the Links Service

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

Section 22.2.1, "Setting up Connections for the Links Service"
Section 22.2.2, "Adding the Links Service at Design Time"
Section 22.2.3, "Setting Security for the Links Service"
Section 22.2.4, "Troubleshooting the Links Service"

22.2.1 Setting up Connections for the Links Service

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

Note:

For details about installing the database and the WebCenter schema, see Oracle Fusion Middleware Installation Guide for Oracle WebCenter.

To create the database connection:

In the Application Navigator, expand the Application Resources panel.
Right-click Connections, then click New Database.
Enter the following information for your database connection:
- Connection Name: WebCenter
- Connection Type: Oracle (JDBC)
- Username: username
- Password: password
- Host: host where you install the WebCenter schema; for example, localhost
- JDBC Port: port; for example, 1521
- SID: system identifier for the database with the same JDBC port; for example, ORCL
You must enter the Connection Name exactly as "WebCenter". There are cases when you may want to leverage an existing database connection for WebCenter services, and it may not be possible to change the database connection name to "WebCenter".

To allow WebCenter services to use another database connection by a different name, you must add the following <data-source> tag as a child of the <wpsC:adf-service-config> element in the adf-config.xml file. (adf-service-config is a child of adf-config, and data-source is a child of adf-service-config or sibling of extension-registry-config.)

For example:
Example 22-1 Adding a data-source Tag in adf-config.xml
```
<adf-config xmlns="http://xmlns.oracle.com/adf/config"
            xmlns:mdsC="http://xmlns.oracle.com/adf/mds/config"
            xmlns:wpsC="http://xmlns.oracle.com/webcenter/framework/service"
            xmlns:jndiC="http://xmlns.oracle.com/adf/jndi/config">
 
    <wpsC:adf-service-config xmlns="http://xmlns.oracle.com/webcenter/framework/service">
        <data-source jndi-name="java:/comp/env/jdbc/NewDatabaseConnDS"/>
   </wpsC:adf-service-config>
</adf-config>
```
Note:
The syntax for jndi-name is "java:/comp/env/jdbc/NewDatabaseConnDS". This is derived from the example name NewDatabaseConn used to create the database connection in the creation wizard.

Figure 22-4 Database Connection

Description of "Figure 22-4 Database Connection"
Click OK.

Note:

While you can set up the connections to back-end servers at design time in Oracle JDeveloper, you can later add, delete, or modify connections in your deployed environment using Enterprise Manager Fusion Middleware Control. For more information, see Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter.

22.2.2 Adding the Links Service at Design Time

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

Section 22.2.2.1, "Links Service Task Flows."
Section 22.2.2.2, "How to Add the Links Service to your Application."

22.2.2.1 Links Service Task Flows

The Links service includes one task flow: Links Dialog.

22.2.2.2 How to Add the Links Service to your Application

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

Follow the steps described in Chapter 3, "Preparing Your Development Environment" to implement security and create a new customizable page in your application.
Ensure that you have set up the database connection to a database with the WebCenter schema installed (Section 22.2.1).
Open the page on which you want to add the Links service.
In the Component Palette, click WebCenter Links Service.
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.
In the Insert Links Detail Button dialog (Figure 22-5), enter a unique object description, ID, and name.

Figure 22-5 Insert Links Detail Button Wizard

Description of "Figure 22-5 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
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.
Click OK.

The new button displays in your page source (Figure 22-6).

Figure 22-6 The Link Detail Button in Your Page Source

Description of "Figure 22-6 The Link Detail Button in Your Page Source"
In the Resource Palette, open My Catalogs, then open the Task Flows folder.
Drag and drop the Links Dialog task flow next to the Link Detail button on your page, and select Region from the context menu.
Save and run your page to the browser.

22.2.3 Setting Security for the Links Service

Links work only on secured p ages. Links icons do not appear on unsecured pages. For information about configuring ADF security, see Section 3.5, "Implementing Security in Your Application."

Table 22-1 shows the permissions granted when you add Links components to a page. Permissions, such as RelationshipPermission are automatically granted to authorized users when a service is consumed.

Table 22-1 Links Service Permissions

Name	Class	Action
`*` (This allows the logged-in user to create and delete links; otherwise, the user sees only available links.)	`oracle.webcenter.relationship.model.security.RelationshipPermission`	manage
`/oracle/webcenter/relationship/view/jsf/resources/links-detail.xml#links-detail`	`oracle.adf.controller.security.TaskFlowPermission`	view
`/oracle/webcenter/relationship/view/jsf/resources/links-detail-popup.xml#links-detail-popup`	`oracle.adf.controller.security.TaskFlowPermission`	view

22.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 4.1.3, "Automated Task Flow Grants."