Introduction

Oracle WebCenter Content, a component of Fusion Middleware, is a strategic solution for the management, security, and distribution of unstructured content such as documents, spreadsheets, presentations, and video. Oracle Fusion Applications leverages Oracle WebCenter Content to store all marketing collateral as well as all attachments. Import flow also uses it to stage the CSV files that the user uploads.

WebCenter Content replaces SSH File Transfer Protocol (SFTP) as a content repository in Fusion Applications starting with Release 7. For example, it is implemented in HCM for File Based Loader (FBL) and Extracts integration. There are several ways of importing and exporting content to and from Fusion Applications such as:

• Upload using "File Import and Export" UI from home page navigation: Navigator > Tools
• Upload using WebCenter Content Document Transfer Utility
• Upload programmatically via Java Code or Web Service API

This post provides an introduction, with working sample code, on how to programmatically export content from Fusion Applications to automate the outbound integration process to other applications in the cloud or on-premise. A Service Oriented Architecture (SOA) composite is implemented to demonstrate the concept.

Main Article

Fusion Applications Security in WebCenter Content

The content in WebCenter Content are secured through user, roles, privileges and accounts. The user could be any valid user with a role such as "Integration Specialist". The role may have privileges such as read, write and delete. The accounts are predefined by each application. For example, HCM uses /hcm/dataloader/import and /hcm/dataloader/export respectively.

Let's review the inbound and outbound batch integration flows.

Inbound Flow

This is a typical Inbound FBL process flow:

The uploaded file is registered by invoking the Loader Integration Service - http://{Host}/hcmCommonBatchLoader/LoaderIntegrationService.

You specify the following in the payload:

• Content id of the file to be loaded
• Business objects that you are loading
• Batch name
• Load type (FBL)
• Imported file to be loaded automatically

Fusion Applications UI also allows the end user to register and initiate the data load process.

Outbound Flow

This is a typical Outbound batch Integration flow using tools such as Business Intelligence (BI) Publishers and Answers and HCM Extracts:

The extracted file could be delivered to the WebCenter Content server.

Programmatic Approach to export files from Webcenter Content

In Fusion Applications, the WebCenter Content Managed server is installed in the Common domain Weblogic Server. The WebCenter Content server provides two types of web services:

Generic JAX-WS based web service

This is a generic web service for general access to the Content Server. The context root for this service is "/idcws". For details of the format, see the published WSDL at https://<hostname>:<port>/idcws/GenericSoapPort?WSDL. This service is protected through Oracle Web Services Security Manager (OWSM). As a result of allowing WS-Security policies to be applied to this service, streaming Message Transmission Optimization Mechanism (MTOM) is not available for use with this service. Very large files (greater than the memory of the client or the server) cannot be uploaded or downloaded.

Native SOAP based web service

This is the general WebCenter Content service. Essentially, it is a normal socket request to Content Server, wrapped in a SOAP request. Requests are sent to the Content Server using streaming Message Transmission Optimization Mechanism (MTOM) in order to support large files. The context root for this service is "/idcnativews". The main web service is IdcWebRequestPort and it requires JSESSIONID, which can be retrieved from IdcWebLoginPort service.

The Remote Intradoc Client (RIDC) uses the native web services. Oracle recommends that you do not develop a custom client against these services.

For more information, please refer "Developing with WebCenter Content Web Services for Integration".

Generic Web Service Implementation

This post provides a sample of implementing generic web service /idcws/GenericSoapPort. In order to implement this web service, it is critical to review the following definitions to generate the request message and parse the response message:

IdcService:

IdcService is a predefined service node's attribute that is to be executed, for example, CHECKIN_UNIVERSAL, GET_SEARCH_RESULTS, GET_FILE, CHECKOUT_BY_NAME, etc.

User

User is a subnode within a <service> and contains all user information.

Document

Document is a collection of all the content-item information and is the parent node of the all the data.

ResultSet

ResultSet is a typical row/column based schema. The name attribute specifies the name of the ResultSet. It contains set of row subnodes.

Row

Row is a typical row within a ResultSet, which can have multiple <row> subnodes. It contains sets of Field objects

Field

Field is a subnode of either <document> or <row>. It represents document or user metadata such as content Id, Name, Version, etc.

File

File is a file object that is either being uploaded or downloaded

For more information, please refer Configuring Web Services with WSDL, SOAP, and the WSDL Generator.

Web Service Security

The genericSoapPort web service is protected by Oracle Web Services Manager (OWSM). In Oracle Fusion Applications cloud, the OWSM policy is: “oracle/wss11_saml_or_username_token_with_message_protection_service_policy”.

In your SOAP envelope, you will need the appropriate "wsee" headers. This is a sample:

<soapenv:Header> <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" soapenv:mustUnderstand="1"> <saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion" MajorVersion="1" MinorVersion="1" AssertionID="SAML-iiYLE6rlHjI2j9AUZXrXmg22" IssueInstant="2014-10-20T13:52:25Z" Issuer="www.oracle.com"> <saml:Conditions NotBefore="2014-10-20T13:52:25Z" NotOnOrAfter="2015-11-22T13:57:25Z"/> <saml:AuthenticationStatement AuthenticationInstant="2014-10-20T14:52:25Z" AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:password"> <saml:Subject> <saml:NameIdentifier Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">FAAdmin</saml:NameIdentifier> <saml:SubjectConfirmation> <saml:ConfirmationMethod>urn:oasis:names:tc:SAML:1.0:cm:sender-vouches</saml:ConfirmationMethod> </saml:SubjectConfirmation> </saml:Subject> </saml:AuthenticationStatement> </saml:Assertion> </wsse:Security> </soapenv:Header>

Sample SOA Composite

The SOA code provides a sample on how to search for a document in WebCenter Content, extract a file name from the search result, and get the file and save it in your local directory. The file could be processed immediately based on your requirements. Since this is a generic web service with a generic request message, you can use the same interface to invoke various IdcServices, such as GET_FILE, GET_SEARCH_RESULTS, etc.

In the SOA composite sample, two external services are created: GenericSoapPort and FileAdapter. If the service is GET_FILE, then it will save a copy of the retrieved file in your local machine.

Export File

The GET_FILE service returns a specific rendition of a content item, the latest revision, or the latest released revision. A copy of the file is retrieved without performing a check out. It requires either dID (content item revision ID) for the revision, or dDocName (content item name) along with a RevisionSelectionMethod parameter. The RevisionSelectionMethod could be either "Latest" (latest revision of the content) or "LatestReleased" (latest released revision of the content). For example, to retrieve file:

<ucm:GenericRequest webKey="cs"> <ucm:Service IdcService="GET_FILE"> <ucm:Document> <ucm:Field name="dID">401</ucm:Field> </ucm:Document> </ucm:Service> </ucm:GenericRequest>

Search File

The dID of the content could be retrieved using the service GET_SEARCH_RESULTS. It uses a QueryText attribute in <Field> node. The QueryText attribute defines the query and must be XML encoded. You can append values for title, content Id, and so on, in the QueryText, to refine the search. The syntax for QueryText could be challenging, but once you understand the special characters formats, it is straight forward. For example, to search content by its original name:

<ucm:Service IdcService="GET_SEARCH_RESULTS"> <ucm:Document> <ucm:Field name="QueryText">dOriginalName &lt;starts&gt; `Test`</ucm:Field> </ucm:Document> </ucm:Service>

In plain text, it is dOriginalName <starts> `Test`. The <substring> is the mandatory format. You can further refine the query by adding more parameters.

This a sample SOA composite with 2 external references, genericSoapPort and FileAdapter.

This is a sample BPEL process flow that demonstrates how to retrieve the file and save a copy to a local directory using File Adapter. If the idcService is GET_SEARCH_RESULTS, then do not save the file. In a real scenario, you will search, check out and start processing the file.

The original file name is preserved when copying it to a local directory by passing the header property to the FileAdapter. For example, create a variable fileName and use assign as follows:

1. get file name from the response message in your <assign> activity as follows:

<from expression="bpws:getVariableData('InvokeGenericSoapPort_GenericSoapOperation_OutputVariable','GenericResponse','/ns2:GenericResponse/ns2:Service/ns2:Document/ns2:ResultSet/ns2:Row/ns2:Field[@name=&quot;dOriginalName&quot;]')"/> <to variable="fileName"/>

Please make note of the XPath expression as this will assist you to retrieve other metadata.

2. Pass this fileName variable to the <invoke> of the FileAdapter as follows:

<bpelx:inputProperty name="jca.file.FileName" variable="fileName"/> 

Please add the following property manually to the ../CommonDomain/ucm/cs/config/config.cfg file for the QueryText syntax: AllowNativeQueryFormat=true
Restart the managed server.
The typical error is: "StatusMessage">Unable to retrieve search results. Parsing error at character xx in query...."

Testing SOA Composite:

After the composite is deployed in your SOA server, you can test it either from Enterprise Manager (EM) or using SoapUI. These are the sample request messages for GET_SEARCH_RESULTS and GET_FILE.

The following screens show the SOA composites for "GET_SEARCH_RESULTS" and "GET_FILE":

Get_File Response snippet with critical objects:

<ns2:GenericResponse xmlns:ns2="http://www.oracle.com/UCM"> <ns2:Service IdcService="GET_FILE"> <ns2:Document> <ns2:Field name="dID">401</ns2:Field> <ns2:Field name="IdcService">GET_FILE</ns2:Field> .... <ns2:ResultSet name="FILE_DOC_INFO"> <ns2:Row> <ns2:Field name="dID">401</ns2:Field> <ns2:Field name="dDocName">UCMFA000401</ns2:Field> <ns2:Field name="dDocType">Document</ns2:Field> <ns2:Field name="dDocTitle">JRD Test</ns2:Field> <ns2:Field name="dDocAuthor">FAAdmin</ns2:Field> <ns2:Field name="dRevClassID">401</ns2:Field> <ns2:Field name="dOriginalName">Readme.html</ns2:Field> </ns2:Row> </ns2:ResultSet> </ns2:ResultSet> <ns2:File name="" href="/u01/app/fa/config/domains/fusionhost.mycompany.com/CommonDomain/ucm/cs/vault/document/bwzh/mdaw/401.html"> <ns2:Contents> <xop:Include href="cid:7405676a-11f8-442d-b13c-f8f6c2b682e4" xmlns:xop="http://www.w3.org/2004/08/xop/include"/> </ns2:Contents> </ns2:File> </ns2:Document> </ns2:Service> </ns2:GenericResponse>

Import File

The above sample can also be use to import files into the WebCenter Content repository for Inbound integration or other use cases. The service name is CHECKIN_UNIVERSAL.

Summary

This post demonstrates how to automate the export and import of contents in WebCenter Content server implemented by Fusion Applications. It further demonstrates how integration tools like SOA can be implemented to automate, extend and orchestrate integration between Fusion Applications in the cloud or on-premise, with Oracle or non-Oracle applications, either in Cloud or on-premise sites.

The SOA sample code is here.