14 Integrating the Documents Service

Oracle WebCenter Framework enables content integration through:

Content Repository data controls, which enable read-only access to a content repository, and maintain tight control over the way the content displays in the application.
The Documents service, which enables users to view and manage documents in your organization's content repositories.

This chapter describes how to integrate the Documents service in your custom WebCenter applications at design time to create a user-friendly interface for managing documents at runtime. For more information about managing and including content in your custom WebCenter applications, see:

Chapter 8, "Integrating Content" to include content in your custom WebCenter applications at design time using JCR data controls.
Chapter 11, "Managing Content Repositories" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter to configure and manage content repositories used by custom WebCenter applications.
Chapter 23, "Working with the Documents Service" in the Oracle Fusion Middleware User's Guide for Oracle WebCenter to work with the Documents service and task flows at runtime in any custom WebCenter application.

This chapter includes the following sections:

Section 14.1, "Introduction to the Documents Service"
Section 14.2, "Basic Configuration for the Documents Service"
Section 14.3, "Advanced Information for the Documents Service"

14.1 Introduction to the Documents Service

The Documents service enables users to view and manage content located in a content repository, such as Oracle Content Server, Oracle Portal, or the file system, from a custom WebCenter application.

14.1.1 Understanding the Documents Service

Depending on the content repository, the Documents service enables users to perform a variety of tasks on content in the repository. Using Oracle Content Server as the repository, for example, users can view, add, and manage files and configure file and folder properties. Figure 14-1 shows an example of one of the Documents service task flows at runtime.

Figure 14-1 Document Library View at Runtime

Description of "Figure 14-1 Document Library View at Runtime"

Note:

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

14.1.2 Requirements for the Documents Service

To use the Documents service, you must have a content repository that contains the documents you want to manage. If the content repository you wish to use requires authentication, ensure that you set up an external application when you configure the connection to your content repository, as mentioned in Section 14.2.1, "Setting Up Connections."

14.2 Basic Configuration for the Documents Service

This section describes the steps to add the Documents service to your application.

14.2.1 Setting Up Connections

Before you can use the Documents service, you must first set up the connection to your content repository. You can reuse connections you've created or create new ones. For information on creating a connection, refer to Section 8.2, "Configuring Content Repository Connections."

Once you set up a connection to a content repository, you can set the connection as active for the Documents service by selecting Set as primary connection for Documents service. You can only set one active connection at a time. If you create another connection and set the new connection as active, the first connection will no longer be active. You can always return to the Properties of the connection (in the Application Resources pane, under Connections, right-click the connection name and choose Properties) to toggle whether the connection is active.

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, refer to the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter.

When you use Oracle Content Server as your content repository, the security settings depend on the connection configuration. If the connection uses External Application Service Public Credentials, there is no need to set up application security.

If the connection uses Identity Propagation, follow the steps described in Section 11.1.1.1, "Implementing Security for Services."

For information on installing the back-end content repository, see Section 4.3.1 "Oracle Content Server Requirements" in the Oracle Fusion Middleware Installation Guide for Oracle WebCenter.

14.2.2 Adding the Documents Service at Design Time

Once you have configured the Documents service with your application, you can add the task flows to your application. Oracle WebCenter Services includes the WebCenter Services Catalog, which contains the task flows you can use with your application at design time.

14.2.2.1 Documents Service Task Flows and Task Flow Parameters

The Documents service contains three task flows: Document Library, Document Library - List View, and Document Library - Recent Documents. Each task flow has its own set of parameters. You configure these values when you add the task flow to your page:

Table 14-1 describes the task flow, the name that displays in the WebCenter Services Catalog, and the content repository with which you can use the task flow. This table also describes the different capabilities a user has for each type of content repository.

Table 14-1 Documents Service Task Flows

Task Flow Content Repository Parameters (* = required) Description

Task Flow	Content Repository	Parameters (* = required)	Description
Document Library	Oracle Content Server Oracle Portal (read and search only) File system (read and write only)	`${connectionName`} `${startFolderPath`}	Provides comprehensive document management functionalities, such as copying, moving, pasting, and deleting files and folders. Section 14.2.2.1.1, "Document Lilbrary Task Flow Parameters" describes the parameters.
Document Library - List View	Oracle Content Server Oracle Portal File system (read and write only)	`${taskFlowInstId`} `${showFolders`} `${connectionName`} `${startFolderPath`} `${creator`} `${lastModifier`} `${createdBefore`} `${createdAfter`} `${lastModifiedBefore`} `${lastModifiedAfter`}	Shows a simple list view of folders and documents, allows users to navigate a folder hierarchy, and enables users to customize search queries. Section 14.2.2.1.2, "Document Library - List View Task Flow Parameters" describes the parameters.
Document Library - Recent Documents	Oracle Content Server	`${connectionName`} `${lastModifier`} `${lastModifiedAfter`} `${lastModifiedBefore`} `${maxDocuments`} `${mostRecentFirst`}	Shows the most recently used documents by the current user. Section 14.2.2.1.3, "Document Library - Recent Documents Task Flow Parameters" describes the parameters.

Document Library

Oracle Content Server
Oracle Portal (read and search only)
File system (read and write only)

${connectionName}

${startFolderPath}

Provides comprehensive document management functionalities, such as copying, moving, pasting, and deleting files and folders. Section 14.2.2.1.1, "Document Lilbrary Task Flow Parameters" describes the parameters.

Document Library - List View

Oracle Content Server
Oracle Portal
File system (read and write only)

${taskFlowInstId}

${showFolders}

${connectionName}

${startFolderPath}

${creator}

${lastModifier}

${createdBefore}

${createdAfter}

${lastModifiedBefore}

${lastModifiedAfter}

Shows a simple list view of folders and documents, allows users to navigate a folder hierarchy, and enables users to customize search queries. Section 14.2.2.1.2, "Document Library - List View Task Flow Parameters" describes the parameters.

Document Library - Recent Documents

Oracle Content Server

${connectionName}

${lastModifier}

${lastModifiedAfter}

${lastModifiedBefore}

${maxDocuments}

${mostRecentFirst}

Shows the most recently used documents by the current user. Section 14.2.2.1.3, "Document Library - Recent Documents Task Flow Parameters" describes the parameters.

14.2.2.1.1 Document Lilbrary Task Flow Parameters

Table 14-2 describes the Document Library task flow parameters.

Table 14-2 Document Library Task Flow Parameters

Task Flow Parameter Type Description Default Value

Task Flow Parameter	Type	Description	Default Value
`connectionName`	String	Optional. The name of the connection to your content repository. If no value is entered, the default connection is used. Example: `${'MyContent'}`	The connection you selected as default in the Create Content Repository Connection dialog box. To select a default, check the Set as primary connection for Documents service checkbox.
`startFolderPath`	String	Optional. The root folder for the document library. Example: `${'/Manuals'}`	The root folder of the content repository you've configured with the specified connection

connectionName

String

Optional. The name of the connection to your content repository. If no value is entered, the default connection is used.

Example: ${'MyContent'}

The connection you selected as default in the Create Content Repository Connection dialog box. To select a default, check the Set as primary connection for Documents service checkbox.

startFolderPath

String

Optional. The root folder for the document library.

Example: ${'/Manuals'}

The root folder of the content repository you've configured with the specified connection

14.2.2.1.2 Document Library - List View Task Flow Parameters

Table 14-3 describes the Document Library - List View task flow parameters.

Table 14-3 Document Library - List View Task Flow Parameters

Task Flow Parameter	Type	Description	Default Value
`taskFlowInstId`	String	A unique identifier for the task flow that is automatically generated when you add the task flow to your application, and used internally for customization. Do not edit this value.	None
`showFolders`	Boolean	Sets whether the listing should show documents and folders (`${true}`), or documents only (`${false}`).	`${false}`
`connectionName`	String	Optional. Connection Name. The name of the connection to your content repository.	The connection you selected as default in the Create Content Repository Connection dialog box. To select a default, check the Set as primary connection for Documents Service checkbox.
startFolderPath	String	Optional. The root folder for the document library.	The root folder of the content repository you've configured with the specified connection
`creator`	String	Optional. The user who created a document. If no value is entered, then documents created by any user display. For example: ${`'monty'}`	None
lastModifier	String	Optional. The user who last modified a document. If no value is entered, then no filtering based on the user who last modified the document is performed. For example: `${'monty'}`	None
`createdBefore`	String	Optional. Limit the display of task flow content to files and folders created before a specified date. If no value is entered, then no "before" filtering using the creation date is applied.The value uses the ISO 8601 format: `${'yyyy-mm-ddThh:mm:ss.zzzTZ'}`^Foot 1 For example: `${'2008-11-14T06:08:02.000+01:00`'}	None
`createdAfter`	String	Optional. Limit the display of task flow content to files and folders created after a specified date. If no value is entered, then no "after" filtering using the creation date is applied.The value uses the ISO 8601 format: `${'yyyy-mm-ddThh:mm:ss.zzzTZ`'}^Footref 1 For example: `${'2008-11-14T06:08:02.000+01:00'}`	None
`lastModifiedBefore`	String	Optional. Limit the display of task flow content to files and folders modified before a specified date. If no value is entered, then no "before" filtering using the last modification date is applied.The value uses the ISO 8601 format: `${'yyyy-mm-ddThh:mm:ss.zzzTZ'}`^Footref 1 For example: ${`'2008-08-07T18:24:36.000Z'}`	None
`lastModifiedAfter`	String	Optional. Limit the display of task flow content to files and folders modified after a specified date.The value uses the ISO 8601 format: `${'yyyy-mm-ddThh:mm:ss.zzzTZ'`}^Footref 1 For example: `${'2008-08-07T18:24:36.000Z`'}	None

^Footnote 1"TZ" is the time zone indicator. If the time being described is in UTC (Coordinated Universal Time), then the time zone indicator is "Z". If the time is from any other time zone, then TZ describes the offset from UTC of the time zone. For example, if the time is in California in December (Pacific Standard Time, PST), then the TZ indicator would be "-08:00".

14.2.2.1.3 Document Library - Recent Documents Task Flow Parameters

Table 14-4 describes the Document Library - Recent Documents task flow parameters.

Table 14-4 Document Library - Recent Documents Task Flow Parameters

Task Flow Parameter	Type	Description	Default Value
`connectionName`	String	Optional. The name of the connection to your content repository. If no value is entered, the default connection is used.	The connection you selected as default in the Create Content Repository Connection dialog box. To select a default, check the Set as primary connection for Documents service checkbox.
`lastModifier`	String	Optional. The user who last modified a document. If no value is entered, then no filtering based on the user who last modified the document is performed. For example: `${'monty'}`	None
`lastModifiedAfter`	String	Optional. Limit the display of task flow content to files and folders modified after a specified date. If no value is entered, then documents modified in the last three months are shown.The value uses the ISO 8601 format: `${'yyyy-mm-ddThh:mm:ss.zzzTZ`'}^Foot 1 For example: `${'2008-08-07T18:24:36.000Z`'}	3 months prior to the current date
`lastModifiedBefore`	String	Optional. Limit the display of task flow content to files and folders modified before a specified date. If no value is entered, then no "before" filtering using the last modification date is applied.The value uses the ISO 8601 format: `${'yyyy-mm-ddThh:mm:ss.zzzTZ`'}^Footref 1 For example: `${'2008-08-07T18:24:36.000Z`'}	None
`maxDocuments`	Long	Optional. The maximum number of documents to show. For example: `${10}`. Note that there is no single quote surrounding 10.	`${null}`
`mostRecentFirst`	Boolean	Optional. The sort order of documents. Use a Boolean type, for example `${true}`. Note that there is no single quote surrounding true. If no value is entered, then the most recent documents display first.	`${true}`

14.2.2.2 How to Add the Documents Service Task Flows at Design Time

To add the Documents service task flows to your custom WebCenter application:

Follow the steps in Section 11.1.1, "How to Prepare Your Application to Consume Services" to implement security and create a customizable page in your application.
Open the customizable page.
Ensure a connection exists to your content repository, or set up the connection to the content repository you wish to use as your document library.

Note:
For more information on creating and setting up connections to your content repository, see Chapter 8, "Integrating Content."
In the Application Resource panel, navigate to Connections, then Content Repository.
Locate the name of your connection, then drag and drop it onto your page.

Figure 14-2 Documents Pop-Up Menu

Description of "Figure 14-2 Documents Pop-Up Menu"
In the menu that displays, choose Documents, Documents - List View, or Documents - Recent Documents, depending on which task flow you wish to use. If the connection you are using does not support a particular task flow, the task flow does not display in this menu. Refer to Table 14-1 for information on the content repositories and the task flows they support.
In the Edit Task Flow Binding dialog box, configure the parameter values. The appearance of this dialog box depends on the task flow you've chosen. For more information on these parameters, see Section 14.2.2.1, "Documents Service Task Flows and Task Flow Parameters."

Figure 14-3 Task Flow Binding Parameters for a Document Library View

Description of "Figure 14-3 Task Flow Binding Parameters for a Document Library View"
Click OK. A new region displays in the Design view of your page.

Figure 14-4 New Document LIbrary Task Flow Region on the Page

Description of "Figure 14-4 New Document LIbrary Task Flow Region on the Page"

Note:
By default, for the Document Library view, users can upload files to the content repository at runtime. For more information, see Section 14.3.2.2, "Uploading Files to Content Repositories."
Save your page and the page definition file, then run your page to your browser. You can do this by right-clicking the page (not the page definition file) and choosing Run.

The Document Library view should display on your page. You can also view the Document Library view in a sample application in the Fusion Order Demo. For more information, see Section 2.2, "Browsing the Oracle WebCenter Framework Components in the Fusion Order Demo for WebCenter at Runtime."

Note:

By default, the task flow displays as full screen at runtime. You can use ADF layout components to modify this layout. To learn more about ADF layout components, refer to the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

14.2.3 Setting Security for the Documents Service

The Documents service task flows support the same security options that are supported by the content repository connections. This service can also use an external application with dedicated user accounts to access remote content repositories, such as an Oracle Content Server or Oracle Portal. For more information about using security with content repositories, see Section 8.1, "Introduction to Content Integration." For information about using external applications, see Section 24.2, "Working with External Applications."

If you are using a content repository that handles its own authentication, such as Oracle Portal or Oracle Content Server, you can associate that content repository with an external application definition to allow for credential provisioning. You can modify your connection to your content repository to use an external application without shared or public credentials. When you do this, the External Application - Change Password task flow is automatically integrated to allow your end users to provide their credentials.

To register an external application for an existing content repository connection:

In the Application Resources pane, right-click your connection name and choose Properties.
In the Edit Content Repository Connection dialog box, under Authentication, select External Application.

Figure 14-5 Selecting External Application in the Content Repository Connection Dialog Box

Description of "Figure 14-5 Selecting External Application in the Content Repository Connection Dialog Box"
Click the green + (plus) sign to start the Register External Application wizard.
On the Name page, enter an application name and application display name, then click Next.

Figure 14-6 Naming the External Application

Description of "Figure 14-6 Naming the External Application"
On the General page, under Authentication Details, choose BASIC from the Authentication Method list, then click Next.

Figure 14-7 Choosing the BASIC Authentication Method

Description of "Figure 14-7 Choosing the BASIC Authentication Method"
On the Additional Fields page, click Next.
On the Shared Credentials page, click Next.
On the Public Credentials page, select Specify Public Credentials, then enter the username and password for the content repository.

Figure 14-8 Specify the Public Credentials

Description of "Figure 14-8 Specify the Public Credentials"
Click Finish. You'll notice that your connection now uses the external application for authentication.

Figure 14-9 Using the New External Application

Description of "Figure 14-9 Using the New External Application"
In the Edit Content Repository Connection dialog box, click OK. In the Application Resources panel, you'll notice the external application now displays.

Figure 14-10 External Application in the Application Resources Panel

Description of "Figure 14-10 External Application in the Application Resources Panel"

If you do not apply security, and the document library requires a login to access the content, the user will not be able to authenticate, and thus will not see any content at runtime.

14.3 Advanced Information for the Documents Service

This section describes how you can use the Documents service with other WebCenter Web 2.0 Services in your application. You will also learn how to use the task flow parameters to modify your Documents service views.

14.3.1 Using the Documents Service with Other WebCenter Web 2.0 Services

You can use the Documents service with a variety of other Oracle WebCenter Web 2.0 Services. For example, you can add tags to documents in your document library, search across your application and retrieve documents in the results, and track recent changes to the document library.

Note:

You can use the Tags service with the Document Library task flow only.

You can see an example of how to use the Documents service with the Tags service in Section 21.3.1, "Optional Way to Show Tags on Pages."

To learn more about how you can use these services together, refer to Section 1.1.4, "Introduction to Oracle WebCenter Web 2.0 Services."

Note:

When you integrate the Documents service with the Search service, the Search service returns results from all content repository connections.

14.3.2 Modifying the Documents Service Task Flow Parameters

The Documents service contains optional parameters that you can set to further enhance the service. You can also modify the parameters after you have added the region to your page.

14.3.2.1 Modifying the Task Flow Binding Parameters

To modify the task flow binding information after you have created the region:

Go to the Bindings view of your page (click the Bindings tab next to the Source tab).
Under Executables, you'll see the task flow you added. Select this task flow. Figure 14-11 shows an example of a Document Library - List View task flow in the Executables section.

Figure 14-11 Document Library - List View Task Flow in the Bindings View

Description of "Figure 14-11 Document Library - List View Task Flow in the Bindings View"
Next to the Executables heading, click the pencil icon to display the Edit Task Flow Binding dialog box
Next to the connectionName parameter, enter the value for your connection. For example, ${'MyContentServer'}.
Next to the startFolderPath parameter, enter the value for your starting path. For example, ${'/'}.

Figure 14-12 Task Flow Binding Parameters

Description of "Figure 14-12 Task Flow Binding Parameters"
Click OK to add the parameters.

14.3.2.2 Uploading Files to Content Repositories

The Document Library enables you to allow users to upload files into content repositories. Oracle WebCenter Framework uses Apache MyFaces Trinidad to handle file upload from a browser to the application server.

To change the default settings of Apache MyFacesTrinidad, you can add three parameters to the web.xml file. To edit this file, open the ViewController project of your application. Under Web Content, open the web.xml file. In the Overview, navigate to Application > Context Initialization Parameters, then click the green plus (+) sign to add the parameters and their values (as described in Table 14-5) or simply update the code in the Source view. After you've made your changes, save the web.xml file, then restart Oracle JDeveloper

Table 14-5 Apache MyFaces Trinidad Parameters

Parameter	Description
UPLOAD_MAX_MEMORY	The maximum amount of memory in kilobytes that a single file can use when uploaded.
UPLOAD_MAX_DISK_SPACE	The maximum amount of disk space in kilobytes that a single file can use when uploaded.
UPLOAD_TEMP_DIR	The directory in which the file being uploaded is temporarily stored.

For more information, see the Apache MyFaces Trinidad documentation, located at http://myfaces.apache.org/trinidad/devguide/fileUpload.html.

14.3.3 Customizing Documents Service Views

You can customize the Documents service views by changing the values of the task flow parameters at design time. This section contains a few examples of how you can adjust the task flow parameters to change the display of the documents at runtime.

14.3.3.1 Displaying Only Recent Documents for the Currently Authenticated User

For example, you can set the task flow binding parameters for the Document Library - Recent Documents task flow to only display recent documents for the currently authenticated user.

To display only recent documents:

Ensure that you've implemented security for your application. For more information, refer to Section 11.1.1.1, "Implementing Security for Services."
Ensure that you have a connection to an Oracle Content Server so that you can use the Document Library - Recent Documents task flow.
From the Application Resources pane, drag and drop the connection name onto your page, and select Documents - Recent Documents View from the menu.

Figure 14-13 Dragging and Dropping the Documents - Recent Documents Task Flow

Description of "Figure 14-13 Dragging and Dropping the Documents - Recent Documents Task Flow"
In the Edit Task Flow Binding dialog box, change the value for the lastModifier parameter to ${securityContext.userName}, as shown in Figure 14-14.

Figure 14-14 lastModifier Task Flow Parameter

Description of "Figure 14-14 lastModifier Task Flow Parameter"
Click OK, then save your page.

14.3.3.2 Customizing the Document Library - List View with Oracle Composer

You and your end users can also customize these views at runtime for the Document Library - List view task flow. To learn more about customizing views at runtime, refer to Chapter 23, "Working with the Documents Service" in the Oracle Fusion Middleware User's Guide for Oracle WebCenter.

14.3.4 Using Adapters with the Documents Service

To learn more about using existing adapters for the content repository connections, see Chapter 8, "Integrating Content."